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Introduction 


Were: to Learn Java 5.0 Swing in a Nutshell for Dummies in 21 Days. Since the beginning 
of Java time (1995), the component libraries have been actively evolving. What began as a small 
set of nine AWT components, plus menus and containers, has grown to a more complete and 
complex set of around 50 Swing components—all just to create graphical user interfaces (GUlIs) 
for your Java client-side programs. That's where this book comes in. Its purpose is to make your 
life easier in creating those GUIs. 

Earlier editions of this book took the approach that if the class wasn't found in the javax. swing 
package, it wasn't covered in the book. This third edition takes a more complete view of creating 
GUIs. For instance, instead of just describing the Swing layout managers, there is also material 
on the AWT layout managers, since you're likely to be using them. 

The first edition of this book was written for a mix of the Java 1.1 and 1.2 developer. The 
second edition hit the 1.3 platform. This edition is wholly for the 5.0 developer. Almost all the 
programs will not work on a 1.4 platform, though with a little tweaking, they can be made to do so. 

In this book, you'll find a tutorial-like approach to learning about the Swing libraries and 
related capabilities. It is not an API reference book, nor is it a primer that describes how to 
install the Java Development Kit DK), compile your programs, or run them. If you need help 
in those areas, consider using an integrated development environment (IDE)—such as IntelliJ 
IDEA, Eclipse, or Borland's JBuilder—or get one of Apress's other books, such as Beginning Java 
Objects, by Jacquie Barker. 

Is this book for you? Ifyou are newto the Java platform, you might want to start with a more 
introductory text first, before jumping on the Swing bandwagon. On the other hand, if you've 
been working with Java for a while and have decided it's time to start using the Swing component 
set, you”1l find this book extremely useful. With this book, you won't have to drudge through the 
countless Swing classes for a way to accomplish that impossible task. You'1l become much more 
productive more quickly, and you'll be able to make the most of the many reusable components 
and techniques available with Swing. 


Book Structure 


This book can be read from cover to cover, but it doesn't have to be done that way. It's true that 
later sections ofthe book assume you've absorbed knowledge from the earlier sections. However, 
if you want to find something on a topic covered in a later chapter, you don't need to read all 
the chapters that precede it first. IfÉyou come across something that's unfamiliar to you, you can 
always go back to the earlier chapter or search the index to locate the information you need. 
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INTRODUCTION 


The contents of this book are grouped into three logical sections: 


Chapters 1 through 4 provide general knowledge that will prove to be useful as you read 
through the remainder of the book. In Chapter 1, you'll find an overview of the Swing 
component set. Chapter 2 details event handling with the Swing component set. It describes 
the delegation-based event model and focus management policies used by Swing. In 
Chapter 3, you'll learn about the Model-View-Controller (MVC) architecture. You can 
avoid using MVC if you wish, but to take full advantage of everything that Swing has to 
offer, it helps to have a good grasp of MVC concepts. In Chapter 4, you”! find the beginning 
coverage of the specific Swing components. All Swing components share many ofthe same 
attributes, and in Chapter 4, you'll learn the foundation for those common behaviors. 


In Chapters 5 through 15, you'll discover the many aspects of the reusable Swing components. 
You"! find out about menus, toolbars, borders, high-level containers, pop-up dialogs, layout 
managers, advanced Swing containers, bounded range components, toggle components, 
list model components, spinners, and text components. Most of what you'll want to accom- 
plish with the Swing libraries is discussed in these chapters. 


In Chapters 16 through 22, some ofthe more advanced Swing topics are covered. These 
tend to be the areas that even the experienced developers find the most confusing. Chapter 16 
goes beyond the basics of text component handling found in Chapter 15. Chapters 17 and 
18 deal with the Swing tree and table components. These components allow you to display 
hierarchical or tabular data. In Chapter 19, you'll learn about drag-and-drop support in 
Swing. Chapter 20 explores how to customize the appearance of your application. Because 
the Swing libraries are completely Java-based, if you don't like the way something is done 
or howitappears, you can changeit. In Chapter 21, you'll learn aboutthe undo framework, 
which offers undo and redo support for your applications. Finally, in Chapter 22, you finish 
off with a look into the accessibility framework offered by Swing, such as support for screen 
readers and magnifying glasses to help those needing assistive technologies. 


The Appendix contains a list of about 1,000 settable properties the user interface manager 


employs to configure the appearance of the Swing components for the current look and feel. 
The Swing components manage various defaults, such as colors and fonts applied to components, 
so you don't need to subclass a component in order to customize its appearance. Appendix A 
gathers all of the property settings listed throughout the chapters into one comprehensive list 
for easy reference. 


Support 


You can head to many places online to get technical support for Swing and answers to general 
Java questions. Here's a list of some of the more useful places around: 


+ TheJava Ranch athttp://www. javaranch.com/ offers forums for just about everything in 
the Big Moose Saloon. 


+ Java Forums at http: //forums.java.sun.com/ are Sun's online forums for Java develop- 
ment issues. 


INTRODUCTION 


+ developerWorks at http://www. ibm.com/developerworks/java/ is the IBM's developer 
community for Java with forums and tutorials. 


* ¡Guru at http://www. jguru.com offers a series Of FAQs and forums for finding answers. 


+ Marcus Green's Java Certification Exam Discussion Forum at http: //www.jchq.net/ 
discus/ provides support for those going the certification route. 


While Iwould love to be able to answer all reader questions, I get swamped with e-mail and 
real-life responsibilities. Please consider using these resources to get help. 


About Java 


Java is one of 13,000 islands that makes up Indonesia, whose capital is Jakarta. Itis home to 
about 120 million people with an area about 50,000 square miles (132,000 square kilometers). 
While on the island, you can hear traditional music such as gamelan or angklung and enjoy 
Java's main export, a coffee that is considered spicy and full-bodied, with a strong, slightly 
acidic flavor. The island also has a dangerous volcano named Merapi, which makes up part 
of the Pacific “Ring of Fire.” In 1891, on the island, Eugene Dubois discovered fossils from 
Pithecanthropus erectus, better known as Java man (homo javanensis). 

For more information, see http://encyclopedia.lockergnome.com/s/b/Java_(island). 
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CHAPTER 1 


Swing Overview 


A-cora:n; to Encyclopedia Britannica, Swing was a popular music in the United States, circa 
1930-1945. Okay, maybe notin the Java sense. Instead, on May 23, 1995, John Gage, then director 
of the Science Office for Sun, introduced Java to the world. With its birth came something called 
the Abstract Window Toolkit, or AWT. In turn, with AWT came native widgets, and with this 
early native widget set came ... trouble. 

The original component set that came with the Java platform, AWT, was dependent on too 
many idiosyncrasies of the underlying platform. Instead of providing a mature-looking compo- 
nent set, Java offered the lowest common denominator version. Ifa feature wasn't available on 
all Java platforms, itwasn't available on any Java platform. And then you had to deal with all the 
browser/platform differences. Each Java runtime environment relied on how the component 
set was connected with the underlying platform-specific native widget set. Ifthere were issues 
with the connection, first, they were specific to the platform (and/or browser) and second, you 
had to code around these problems so your programs could be write-once, run anywhere 
(WORA), the Java mantra of the time. 

As Java technologies became more popular, users realized AWT was extremely slow and 
unreliable, and you couldn't really do much with the provided components. Very few of them 
were available, and you couldn't use them in a visual programming environment. So, new 
technologies were introduced, such as just-in-time (JIT) compilers to improve performance 
and, with Borland's help, JavaBeans for a component-based development. 

With these new technologies came more and more widget sets, for the AWT component 
set itself was very basic. So, applet download times grew and grew, because these new widget 
sets weren't part ofthe core Java platform, and Java archive (JAR) files were introduced to 
improve delivery time. Eventually, each of the major browser vendors added its favorite 
component library to its virtual machine—AFC, IFC, and WFC, to name just a few. Yet all the 
libraries used different design models, and there were no true cross-browser standards. 

Eventually, Sun Microsystems teamed up with Netscape Communication and other partners 
to create yet another library called the Java Foundation Classes, or JFC. Part of FC is something 
called the Swing component set. This Swing component set is what this book is all about. 


CHAPTER 1 SWING OVERVIEW 


Note Later technologies were introduced to help people use the Swing components within a browser and 
with web-based application delivery. These include the Java Plug-in (http: //java.sun.com/products/ 
plugin/) and Java Web Start (http: //java.sun.com/products/javawebstart/). Alternatives to 
Swing, like the SWT component set with Eclipse (http: //www.eclipse.org/swt/), have also been 
created. These are not discussed here. 


This chapter will familiarize you with the various Swing pieces. For starters, there is the 
component set. Without these, there is no Swing. Next, you'll peek at the world of event handling 
and layout management common to both AWT and Swing components. After that, you'll take 
a quick look at the undo/redo framework available within the Swing architecture. Then you'll 
explore the SwingSet2 demonstration provided with the Java 2 Platform Standard Edition 5.0 
Development Kit (JDK 5.0) so that you can see some of the capabilities. Lastly, 111 point out 
where in the book all these capabilities are discussed in detail. 


Getting to Know the Swing Components 


The book will serve as a guide to development using the Swing component set. Over the course 
of its pages, you”! look at every package in the javax. swing package hierarchy, as shown in 
Figure 1-1. 


lalx 
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IN] colorchooser 
Q event 
Q filechooser 
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Ey table 
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O parser 
Dr 
B tree 
Ey undo 


Figure 1-1. The Swing package hierarchy 


Note The javax.swing.plaf package contains several subpackages and related packages, some of 
which are located outside the javax. swing package hierarchy. Plafstands for pluggable look and feel — 
a Swing concept that will be described more fully in Chapter 20. 
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The Swing component set is one big group of components. While the JDK 5.0 release 
didn't add any new Swing components to the mix, logically, you can think of them as those 
with duplicate components within AWT and those without. 


AWT Component Replacements 


The Swing component set was originally created because the basic AWT components that came 
with the original version of the Java libraries were insufficient for real-world, forms-based 
applications. All the basic components were there, but the existing set was too small and far 
too restrictive. For instance, you couldn't even put an image on a button. To alleviate this situ- 
ation, the Swing component set offers replacements for each ofthe AWT components. The 
Swing components support all the capabilities of the original set and offer a whole lot more 
besides. As such, you should never need to deal with any of the basic AWT components. 


Note Although the Swing components replace the AWT components, you'll still need to understand 
several basic AWT concepts, such as layout managers, event handling, and drawing support. In addition, 
you”!! need to grasp the concept that all of Swing is built on top of the core AWT libraries. 


The basic distinction between the Swing and equivalent AWT components is, in most cases, 
the Swing component class names begin with a J and the AWT ones don't. Swing's JButton is a 
replacement for the AWT Button component. One exception is the JComboBox, which replaces 
the AWT Choice component. 

At the application programming interface (API) level, the Swing components are almost 
always a superset ofthe features the AWT components support. While they support additional 
capabilities, the basic AWT capabilities are there for everything but the JList component, 
whose API is completely unlike that of the AWT List component. Table 1-1 maps the original 
AWT components to their replacement Swing components. 


Table 1-1. AWT to Swing Component Mapping 


AWT Component Nearest Swing Replacement 
Button JButton 

Canvas JPanel 

Checkbox JCheckBox 

Checkbox in CheckboxGroup JRadioButton in ButtonGroup 
Choice JComboBox 

Component JComponent 

Container JPanel 

Label JLabel 


List Jlist 
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Table 1-1. AWT to Swing Component Mapping (Continued) 


AWT Component Nearest Swing Replacement 
Menu JMenu 

MenuBar JMenuBar 

Menultem JMenultem 

Panel JPanel 

PopupMenu JPopupMenu 

Scrollbar JScrollBar 

ScrollPane JScrollPane 

TextArea JTextArea 

TextField JTextField 


Note For most people, the fact that the Swing components replace AWT components is irrelevant. 
Just treat the Swing components as an independent component set, and you!!! be perfectly okay. 


To help you understand how to use the Swing components, you'll examine each of the 
components in this book. For instance, Chapter 4 looks at how the JButton component works, 
with just a single line of text as its label, like an AWT Button, but adds capabilities, such as using 
image icons on buttons and working with multiple lines of text. To find out where each compo- 
nentis discussed in this book, see the “Swing Component to Chapter Mapping” section later in 
this chapter. 

In addition to replacing each of the basic components, the Swing component set has a 
replacement for the higher-level window objects. Although the only change in most of the 
components' namesis the beginning J, you'll discover in Chapter 8 how the high-level container 
objects are much different in the Swing world. Swing's replacement for the old FileDialog object 
differs even more and is discussed in Chapter 9. Table 1-2 maps the high-level window objects 
from the AWT component world to the Swing universe. 


Table 1-2. AWT to Swing Window Mapping 


AWT Window NearestSwing Replacement 
Apple TAL 
Dialog JDialog 

FileDialog JFileChooser 

Frame JFrame 


Window JWindow 
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Whereas the AWT components rely on the user's operating system to provide the actual 
component to a Java program, Swing components are all controlled from within the Java 
runtime. The AWT approach is called either the heavyweight or the peered approach; most 
Swing components are lightweight or peerless. You'll explore the basics of this approach in 
Chapter 4 with the JComponent. Additional features for customizing the look and feel of compo- 
nents are discussed in Chapter 20. 


Non-AWT Upgraded Components 


In addition to offering replacements for all the basic AWT components, the Swing component 
set includes twice as many new components. 


Note If you're new to Java, just think of all of these components—both the AWT component replacements 
and those that were not in the AWT—as one big set of components, versus two distinct sets. 


Here's a look at those components that didn't originate in the AWT world: 


» JPasswordField: This specialized text field is for password entry, as shown in Figure 1-2. 
You cannot use cut or copy operations within the component, but you can paste text 
into it. 


£ JPasswordField Sample jaj ES! 


Username|Regular Text Field | 


Password| == 


Figure 1-2. The Swing JPasswordField 


+ JEditorPane and JTextPane: These two components provide support for displaying and 
editing multiple-attributed content, such as an HTML and RTF viewer. Figure 1-3 shows 
a JEditorPane component. 


£ JEditorPane Sample 101 x/ 


Figure 1-3. The Swing JEditorPane 
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+ JSpinner: This component, shown in Figure 1-4, provides selection from an ordered set 
of predefined values, offering arrows to scroll through the next and previous choices. 
The predefined values can be an array of strings, a sequential set of numbers, or a date. 


lola 
vendredi 5] 
1/30/05 9:21 PM = 


Figure 1-4. The Swing JSpinner 


+ JToggleButton: This component offers a button that stays depressed when selected. In 
the example shown in Figure 1-5, the North, East, and South buttons are depressed. 


olx 
North 
Center East 


Figure 1-5. The Swing JToggleButton 


+ JSlider: This components like the Scrollbar component of AWT (or JScrol1Bar in the 
Swing component set). However, its purpose in Swing is for user input. It offers various 
clues to help the user choose a value. Figure 1-6 shows an example of a JS1ider component. 
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Figure 1-6. The Swing JSlider 


+ JProgressBar: This component allows the user to visually see the progress of an activity. 
Some options available include showing static text or percentage done, as shown in 
Figure 1-7. 


£ JProgressBar Sample =10/xÍ 


Reading... 


25% 


Figure 1-7. The Swing JProgressBar 
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+ JFormattedTextField: This component provides for the input of formatted text, like 


numeric values, phone numbers, dates, or social security numbers. Figure 1-8 shows 
two examples of this component. 


£ JFormattedTextField Sample =10/ xf 


SSN;| - - 


Telephone sl lo. 


Figure 1-8. The Swing JFormattedTextField 


JTable: This component provides for the display of two-dimensional row and column 
information, such as stock quotes, as in the example shown in Figure 1-9. 


101 xi 
Symbol Name Price [ 

AMZN Amazon 38.94 

DCLK DoubleClick 7.70 

EBAY eBay 112.65 

Google 181.05 

MET MarketWatch 18.08 

SAP SAP AG 45.35 

SUN Sun Microsyst... [5.51 

MRS Time Warner [17.82 

WOD Vodafone Group[27.39 

YHnn Yahon! 2812 


Figure 1-9. The Swing JTable 


JTree: This component supports the display of hierarchical data. Figure 1-10 shows an 
example of a JTree component. 


lol 
ES 


IN] violet 
IN] red E] 
A yellow 

9- sports 

Ey basketball 
Fr soccer 


4] 


Figure 1-10. The Swing JTree 


JToo1Tip: Through this component, all Swing components support pop-up text for 


offering useful tips. Figure 1-11 shows an example of a JToo1Tip component added to 
a JSlider. 
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Figure 1-11. The Swing JToolTip 


+ JToolBar: This container offers a draggable toolbar to be included within any program 
window, as shown in Figure 1-12. 


[2 sroolar sample A 


£ 5 


D— 
D— 


Figure 1-12. The Swing JToolBar 


+ JRadioButtonMenultem: This component is an addition to the set of menu components. 
With it, you can have radio buttons on a menu for mutually exclusive choices, as shown 
in the example in Figure 1-13. There's also a JCheckBoxMenuTtem component, for when 
you don't need mutually exclusive choices. 


£ JRadioButtonMenultem Sample: =10/ xj 


Figure 1-13. The Swing JRadioButtonMenultem 


+ JSeparator: The menu's separator bar is now its own component and can be used 
outside of menus, too, as shown in Figure 1-14. 


£ JSeparator Sample 101 x/ 


Above Separator 


Below Separator 


Figure 1-14. The Swing JSeparator 


+ JDesktopPane and JInternalFrame: This pair of components allows you to develop appli- 
cations using the familiar Windows Multiple Document Interface (MDI). Figure 1-15 
shows an example. 
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£ JDesktopPane Sample =10/xÍ 


Open 2 om 


Iconified 


Figure 1-15. The Swing JDesktopPane and JInternalFrame 


+ JOptionPane: This component allows you to easily create pop-up windows with varied 
content, as shown in Figure 1-16. 


JOptionPane Sample xl 


Where do you want to go tomorrow? 


Cancel 


Figure 1-16. The Swing JOptionPane 


+ JColorChooser: This componentis for choosing a color, with different views available to 
select the color, as shown in Figure 1-17. 


£ JColorChooser Sample E. xj 
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Red AAN 2087 
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Preview 
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E En 


Sample Text Sample Text 


[ox ] Cancel Reset 


Figure 1-17. The Swing JColorChooser 
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+ JSplitPane: This container allows you to place multiple components in a window. It also 
allows the user control over how much of each component is visible. Figure 1-18 shows 
an example ofa JSplitPane. 


£ JSplitPane Sample 101 x/ 
left button right button 


Figure 1-18. The Swing JSplitPane 


+ JTabbedPane: This component is like a container whose layout manager is CardLayout 
(discussed in Chapter 10), with labeled tabs automatically provided to allow the user 
to swap cards. This provides you with the familiar property-sheet motif, as shown in 
Figure 1-19. 


£ JTabbedPane Sample =10/x/ 


Tab Three | Tab Four [[ Tab Five 


Tab One Tab Two | 


tao 


Figure 1-19. The Swing JTabbedPane 


You'll learn about all of these components throughout this book. Refer to the “Swing 
Component to Chapter Mapping” section later in this chapter to see where each component 
is covered. 


Event Handling and Layout Management 


To use the Swing components successfully, you must understand the underlying parts of the 
original AWT component set. For instance, the Swing components all support the delegation- 
based event model, which was introduced with JDK 1.1 and is supported by the AWT 1.1 
component set. In addition, layout managers control screen layout. 
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Note The Swing components don't support the original JDK 1.0 event model. They no longer use the 
public boolean handleEvent(Event) method and all its helper methods. If you need to convert an 
AWT program that uses the JDK 1.0 event model to one that uses the Swing components, you'll need to 
convert the program to use the delegation-based event model, in addition to changing the component set. 


Although directly porting old Java AWT programs (or programme:rs!) to Swing programs is 
done most easily by continuing to use the delegation-based event model, this solution is rarely 
the best one. Besides supporting the delegation-based event model, the Swing components 
provide other, more efficient ways of dealing with events for components. In Chapter 2, you'll 
explore the delegation-based event model and look at the other ways of managing event handling. 

In addition to the delegation-based event-handling support, the Swing components use 
the Model-View-Controller (MVC) design to separate their user interfaces from their underlying 
data models. Using the MVC architecture provides yet another way of event handling with a 
Swing component. While MVC might be new to most developers, the basic constructs use the 
delegation-based event model. MVC provides the optimal way of working with the Swing 
components. You'll find an overview of the MVC architecture in Chapter 3. 

Besides all the support for extended event handling with the Swing classes, these classes 
share the need to use a layout manager for positioning components on the screen. In addition 
to using the layout managers that come with AWT, you can use other layout managers that 
come with the Swing classes. In Chapter 10, you'll learn about both the AWT and Swing layout 
managers. 


Undo Framework 


Situated within the javax. swing class hierarchy are the javax.swing.undo classes. These classes 
offer a framework for supporting undo and redo capabilities within Java programs. Instead of 
creating the basic framework yourself, the framework is provided as part of the Swing classes. 
Although the undo classes don't use anything directly outside their package, the Swing text 
components use the undo functionality. Chapter 21 provides a detailed explanation ofundo. 


SwingSet Demonstration 


As part of the demo/jfc directory with the Java 2 platform, you have available a Swing demon- 
stration program called SwingSet2. This program provides a quick preview ofthe majority of 
the Swing capabilities. All the source code is included, so if you see something you like and are 
interested in learning how it was done, just dig through the code to find the appropriate lines. 

With the Java 2 platform, you start up this demonstration from the SwingSet2 directory 
with the java -jar SwingSet2.jar command. After starting the SwingSet2 demonstration, you 
see the opening screen, as shown in Figure 1-20. 
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Rx 
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Frame title: [Frame 


Press Shif-F10 to activate popup menu 


Figure 1-20. SwingSet2 startup screen 


Choose the different buttons and tabs to see many of the features supported by the Swing 
components. 


Swing Component to Chapter Mapping 


The Swing packages contain many classes and components. To help you find where all the 
different components are discussed, Table 1-3 provides a handy reference (with the components 
listed alphabetically). 


CHAPTER 1 


Table 1-3. Mapping of Swing Components to Chapters in This Book 


Swing Component 


Box 

JApplet 

JButton 

JCheckBox 
JCheckBoxMenuItem 
JColorChooser 
JComboBox 
JComponent 
JDesktopPane 
JDialog 
JEditorPane 
JFileChooser 
JFormattedTextField 
JFrame 
JInternalFrame 


JLabel 


u 


LayeredPane 
JList 
JMenu 


JMenuBar 


JMenultem 
JOptionPane 

JPanel 
JPasswordField 
JPopupMenu 
JProgressBar 
JRadioButton 
JRadioButtonMenultem 


Chapter 
11 


8 
4 
5 
6 
9 


13 
4 
8 
8 
15 


15 
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Table 1-3. Mapping of Swing Components to Chapters in This Book (Continued) 


Swing Component Chapter 
JRootPane 8 
JScrollBar 12 
JScrollPane 11 
JSeparator 6 
Jslider 12 
JSpinner 14 
JSplitPane 11 
JTabbedPane 11 
JTable 18 
JTextArea 15 
JTextField 15 
JTextPane 15 
JToggleButton 5 
JTool1Bar 6 
JToo1Tip 4 
JTree 17 
JViewport 11 
JWindow 8 


In addition to information about using the different components, the following chapters 
feature a table for each component that lists the JavaBeans properties defined by that compo- 
nent. Each table notes whether a property has a setter (setPropertyName (newValue)), a getter 
(getPropertyName()), or an isPropertyName () method defined by the class, and whether a 
property is bound (you can listen for a PropertyChangeEvent). In these property tables, inherited 
properties aren't listed, so even though a property for a component is listed as write-only, the 
parent class might still provide a getter method. As an example, Table 1-4 shows the property 
table for the JScrol1Bar component. 


Table 1-4. JScrollBar Properties 


Property Name Data Type Access 
accessibleContext AccessibleContext Read-only 
adjustmentListeners AdjustmentListener[ ] Read-only 
blockIncrement int Read-write bound 


enabled boolean Write-only 


Table 1-4. JScrollBar Properties (Continued) 


CHAPTER 1 SWING OVERVIEW 


Property Name Data Type Access 

maximum int Read-write 
maximumSize Dimension Read-only 
minimum int Read-write 
minimumSize Dimension Read-only 

model BoundedRangeModel Read-write bound 
orientation int Read-write bound 
UI ScrollBarul Read-write bound 
UlClassID String Read-only 
unitIncrement int Read-write bound 
value int Read-write bound 
valuelsAdjusting boolean Read-write bound 
visibleAmount int Read-write 


Besides the property tables, you'll find information about important aspects of each 
component and the techniques for using them. 


Note This book is not intended to be an API reference, nor does it cover everything about each component. 
For the lesser-used aspects of a component, see the online javadoc documentation. 


Summary 


This chapter provided a brief overview of what will be covered in this book, such as the many 
essential parts of the Swing component set you need to understand in order to use Swing 
components. The combined set of javax.swing packages is larger than the entire first JDK, if 
not the first two. 

In Chapter 2, you'll explore how to deal with the many aspects of event handling using the 
Swing components. In addition to reviewing the delegation-based event model, you'll look at 
different ways you can deal with events when using Swing components and get a grasp of the 
focus traversal policies involved with Swing. 
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CHAPTER 2 


Event Handling with the Swing 
Component Set 


a 1 provided a brief overview of the Swing component set. In this chapter, you will 
start to look at the details of one aspect of using Swing components: event handling. When 
working with the Swing component set, the delegation-based event-handling mechanism is 
available, but you can also take advantage of several additional ways to respond to user-initiated 
actions (as well as to programmatic events). In this chapter, you'll explore all these event-handling 
response mechanisms. You'll also learn how Swing manages input focus and some techniques 
for controlling how focus is handled. 

As you explore event-handling capabilities, you will start to look at some actual Swing 
components. In this chapter, you will be using the components in the simplest manner possible. 
Feel free to first read up on the components covered in later chapters of this book, and then 
come back to this chapter for a general discussion of event handling. The later chapters of this 
book also contain specific details on event handling for each component. 


Delegation-Based Event Handling 


Sun Microsystems introduced the delegation-based event-handling mechanism into the Java 
libraries with the release ofJDK 1.1 and JavaBeans. Although the Java 1.0 libraries included the 
Observer-Observable pair of objects that followed the Observer behavioral design pattern, this 
wasn't an adequate long-term solution for user-interface programming. (The Java 1.0 contain- 
ment event-handling mechanism was even worse.) 


Event Delegation Model 


The delegation-based event-handling mechanism is a specialized form of the Observer design 
pattern. The Observer pattern is used when an Observer wants to know when a watched 
object's state changes and what that state change is. In the case ofthe delegation-based event- 
handling mechanism, instead ofthe Observer listening for a state change, the Observer listens 
for events to happen. 
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Figure 2-1 shows the structure ofthe modified Observer pattern as it relates to the specific 
classes within the Java libraries for event handling. The generic Subject participant in the 
pattern manages a list (or lists) of generic Observer objects for each event that the subject can 
generate. The Observer objects in the list must provide a specific interface through which the 
Subject participant can notify them. When an event that the Observer objects are interested in 
happens within the Subject participant, all the registered Observer objects are notified. In 
the Java world, the specific interface for the Observer objects to implement must extend the 
java.util.EventListener interface. The specific event the Subject participant must create 
needs to extend the java.util.EventObject class. 


AAA 
+addAnEventListener() 


+removeAnEventListener() 
+fireEventHappened() 


== AA 2220 
<< Interface>> 
—— 


IS 
AnEvent event=new AnEvent(...); 
for each listener (listener): 
listener.eventHappened(event) 


5 _ _ E 2 0... 
AnEvent 7 antericas> > 
AnEveniListener Ei 
eventState:datatype 
+getEventstate():datatype |+eventHappened( | |+eventHappened( | 


Figure 2-1. The modified Observer pattern 


To make this a little clearer, let's take a second look at the delegation-based event-handling 
mechanism without all the design pattern terms. GUI components (and JavaBeans) manage 
lists of listeners with a pair of methods for each listener type: addXXXListener() and 
removeXXXListener(). When an event happens within the subject component, the component 
notifies all registered listeners ofthe event. Any observer class interested in such an event 
needs to register with the component an implementer of the appropriate interface. Then each 
implementation is notified when the event happens. Figure 2-2 illustrates this sequence. 


Note Some users like to call the event delegation model a publish-subscribe model, in which components 
publish a set of available listeners for subscription, and others can subscribe to them. 
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Observer(s) Subject 


Registers with 


Notifies 


Figure 2-2. Event delegation sequence diagram 


Event Listeners As Observers 
Using event listeners to handle an event is a three-step process: 


1. Define a class that implements the appropriate listener interface (this includes 
providing implementations for all the methods of the interface). 


2. Create an instance of this listener. 


3. Register this listener to the component whose events you're interested in. 


Let's take a look at the three specific steps for creating a simple button that responds to 
selection by printing a message. 


Defining the Listener 


To set up event handling for a selectable button, you need to create an ActionListener, because 
the JButton generates ActionEvent objects when selected. 


class AnActionListener implements ActionListener ( 
public void actionPerformed(ActionEvent actionEvent) ( 
System.out.println("I was selected."); 
) 
J 
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Note Part of the problem of creating responsive user interfaces is figuring out which event listener to 
associate with a component to get the appropriate response for the event you're interested in. For the most 
part, this process becomes more natural with practice. Until then, you can examine the different component 
APIs for a pair of add/remove listener methods, or reference the appropriate component material in this book. 


Creating an Instance of the Listener 


Next, you simply create an instance of the listener you just defined. 
ActionListener actionListener = new AnActionListener(); 
If you use anonymous inner classes for event listeners, you can combine steps 1 and 2: 


ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) f 
System.out.println("I was selected."); 
J 
5 


Registering the Listener with a Component 


Once you've created the listener, you can associate it with the appropriate component. Assuming 
the JButton has already been created with a reference stored in the variable button, this would 
merely entail calling the button's addActionListener() method: 


button.addActionListener(actionListener); 


If the class that you're currently defining is the class that implements the event listener 
interface, you don't need to create a separate instance ofthe listener. You just need to associate 
your class as the listener for the component. The following source demonstrates this: 


public class YourClass implements ActionListener ( 

. // Other code for your class 

public void actionPerformed(ActionEvent actionEvent) f 
System.out.println("I was selected."); 

J 

// Code within some method 

JButton button = new JButton(...); 

button.addActionListener(this); 

// More code within some method 


Using event handlers such as creating a listener and associating it to a component is the 
basic way to respond to events with the Swing components. The specifics of which listener 
works with which component are covered in later chapters, when each componentis described. 
In the following sections, you”1l learn about some additional ways to respond to events. 
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Tip Personally, | don't like the approach of just associating a class as the event listener, because it doesn't 
scale well when the situation gets more complicated. For instance, as soon as you add another button onto 
the screen and want the same event listener to handle ¡ts selection, the actionPerformed() method must 
figure out which button triggered the event before it can respond. Although creating a separate event listener 
for each component adds another class to the set of deliverables, creating separate listeners is more main- 
tainable than sharing a listener across multiple components. In addition, most integrated development 
environment (IDE) tools, such as Borland's JBuilder, can automatically create the listener objects as separate 
classes. 


Multithreaded Swing Event Handling 


To increase their efficiency and decrease the complexity, all Swing components were designed 
to not be thread-safe. Although this might sound scary, it simply means that all access to Swing 
components needs to be done from a single thread—the event-dispatch thread. Ifyou are 
unsure that you're in a particular thread, you can ask the EventQueue class with its public static 
boolean isDispatchThread() method orthe SwingUtilities class with its public static boolean 
isEventDispatchThread() method. The latter just acts as a proxy to the former. 


Note Earlier versions of this book showed one particular way of creating Swing programs. They were 
wrong. lt was thought that accessing invisible (unrealized) components from outside the event-dispatch 
thread was okay. However, that's not true. Doing something with a Swing component can trigger a reaction 
within the component, and that other action would be done on the event-dispatch thread, violating the single- 
threaded access. 


With the help of the EventQueue class, you create Runnable objects to execute on the event- 
dispatch thread to properly access components. Ifyou need to execute a task on the event-dispatch 
thread, but you don't need any results and don't care exactly when the task finishes, you can 
use the public static void invokeLater(Runnable runnable) method of EventQueue. If, on the 
other hand, you can't continue with what you're doing until the task completes and returns 
a value, you can use the public static void invokeAndWait(Runnable runnable) method of 
EventQueue. The code to get the value is left up to you and is not the return value to the 
invokeAndWait() method. 


Caution The invokeAndWait(Runnable) method can throw an InterruptedException or an 
InvocationTargetException. 
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To demonstrate the proper way to create a Swing-based program, Listing 2-1 shows the 
source for a selectable button. 


Listing 2-1. Swing Application Framework 


import javax.swing.*; 
import java.awt.*; 
import java.awt.event.*; 


public class ButtonSample ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("Button Sample”); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
JButton button = new JButton("Select Me"); 


// Define ActionListener 
ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
System.out.println("I was selected."); 
j 
E 


// Attach listeners 
button.addActionListener(actionListener); 


frame.add(button, BorderLayout.SOUTH); 
frame.setSize(300, 100); 
frame.setVisible(true); 
) 
E 
EventQueue.invokeLater(runner); 
) 
) 


This code produces the button shown in Figure 2-3. 


HE 


Select Me 


Figure 2-3. Button sample 


First, let's look at the invokeLater() method. It requires a Runnable object as its argument. 
You just create a Runnable object and pass it along to the invokeLater() method. Some time 
after the current event dispatching is done, this Runnable object will execute. 
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Runnable runnable = new Runnable() 4 
public void run() £ 
// Do work to be done 
) 
J 


EventQueue.invokelLater(runnable); 


If you want your Swing GUI creation to be thread-safe, you should follow this pattern with 
all of your Swing code. If you need to access the command-line arguments, just add the final 
keyword to the argument declaration: public static void main(final String args[]). This 
may seem like overkill for a simple example like this, but it does ensure the thread safety ofyour 
program, making sure that all Swing component access is done from the event-dispatch thread. 
(However, calls to repaint(), revalidate(), and invalidate() don't need to be done from the 
event-dispatch thread.) 


Note In addition to the invokeLater() and invokeAndWait() methods of the EventQueue class, there 
are wrapper methods of the same name in the SwingUtilities class. Since the SwingUtilities calls just 
redirect the calls on to the EventOQueue class, you should avoid the extra layer of indirection and access 
EventQueue directly. These wrapper methods were created for an early Swing version, prior to the existence 
of the Event0Queue class. 


One additional line from Listing 2-1 requires some extra explanation: 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


By default, if you click the little X in the title bar of the window shown in Figure 2-3, the 
application does not close; instead, the frame is made invisible. Setting the default close oper- 
ation to JFrame.EXIT_ON_CLOSE, as in Listing 2-1, causes the application to exitifthe user clicks 
the X. You'll learn more about this behavior in Chapter 8, which explores the JFrame class. 


Using SwingUtilities for Mouse Button Identification 


The Swing component set includes a utility class called SwingUtilities that provides a collection 
of generic helper methods. You will look at this class periodically throughout this book when a 
particular set of methods for this class seems useful. For the button example in Listing 2-1, the 
methods of interest are related to determining which mouse button has been selected. 

The MouseInputListener interface consists of seven methods: mouseClicked(MouseEvent), 
mouseEntered (MouseEvent), mouseExited(MouseEvent), mousePressed(MouseEvent), and 
mouseReleased(MouseEvent) from MouseListener; and mouseDragged(MouseEvent) and 
mouseMoved(MouseEvent) from MouseMotionListener. If you need to determine which buttons 
on the mouse were selected (or released) when the event happened, check the modifiers prop- 
erty of MouseEvent and compare it to various mask-setting constants of the InputEvent class. 

For instance, to check if a middle mouse button is pressed for a mouse press event, you 
could use the following code in your mouse listener's mousePressed() method: 
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public void mousePressed(MouseEvent mouseEvent) ( 
int modifiers = mouseEvent.getModifiers(); 
if ((modifiers 8 InputEvent.BUTTON2_MASK) == InputEvent.BUTTON2_MASK) £ 
System.out.println("Middle button pressed."); 
) 
) 


Although this works fine and dandy, the SvuingUtilities class has three methods to make 
this process much simpler: 


SwingUtilities.isLeftMouseButton(MouseEvent mouseEvent) 
SwingUtilities.isMiddleMouseButton(MouseEvent mouseEvent) 
SwingUtilities.isRightMouseButton(MouseEvent mouseEvent) 


Now, instead of needing to manually get the modifiers and compare them against the 
mask, you can simply ask the SuingUtilities, as follows: 


if (SwingUtilities.isMiddleMouseButton(mouseEvent)) ( 
System.out.println("Middle button released."); 


J 


This makes your code much more readable and easier to maintain. 
Listing 2-2 contains an updated ButtonSample that adds another listener to detect which 
mouse button was pressed. 


Listing 2-2. Button Sample with Mouse Button Detection 


import javax.swing.*; 
import java.awt.*; 
import java.awt.event.*; 


public class ButtonSample ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("Button Sample”); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
JButton button = new JButton("Select Me"); 


// Define ActionListener 
ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
System.out.println("I was selected."); 
) 
E 


J 
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// Define MouseListener 
MouseListener mouseListener = new MouseAdapter() f 
public void mousePressed(MouseEvent mouseEvent) ( 
int modifiers = mouseEvent.getModifiers(); 
if ((modifiers 8 InputEvent.BUTTON1_MASK) == 
InputEvent.BUTTON1_MASK) £ 
System.out.println("Left button pressed."); 
) 
if ((modifiers 8 InputEvent.BUTTON2_MASK) == 
InputEvent.BUTTON2_MASK) ( 
System.out.println("Middle button pressed.”); 
) 
if ((modifiers 4 InputEvent.BUTTON3_MASK) == 
InputEvent.BUTTON3_MASK) ( 
System.out.println("Right button pressed."); 


A 
J 


public void mouseReleased(MouseEvent mouseEvent) ( 

if (SwingUtilities.isLeftMouseButton(mouseEvent)) ( 
System.out.println("Left button released."); 

y 

if (SwingUtilities.isMiddleMouseButton(mouseEvent)) ( 
System.out.println("Middle button released."); 

) 

if (SwingUtilities.isRightMouseButton(mouseEvent)) ( 
System.out.println("Right button released."); 

q 

System.out.println(); 


J 


E; 


// Mttach listeners 
button.addActionListener(actionListener); 
button.addMouseListener(mouseListener); 


frame.add(button, BorderLayout. SOUTH); 
frame.setSize(300, 100); 
frame.setVisible(true); 
J 
5 


EventQueue.invokeLater(runner); 
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Using Property Change Listeners As Observers 


Besides the basic event-delegation mechanism, the JavaBeans framework introduced yet 
another incarnation ofthe Observer design pattern, this time through the property change 
listener. The PropertyChangeListener implementation is a truer representation ofthe Observer 
pattern. Each Observer watches for changes to an attribute ofthe Subject. The Observer is then 
notified of the new state when changed in the Subject. Figure 2-4 shows the structure of this 
Observer pattern as it relates to the specific classes within the JavaBeans libraries for property 
change handling. In this particular case, the observable Subject has a set of add/remove prop- 
erty change listener methods and a property (or properties) whose state is being watched. 


<<Interface>> 
EventObject EventListener 
ttsource:Object 


+getSource():Object 
A 


Subject 


-state:datatype 
-propertyChangeSupport:propertyChangeSupport 
+addPropertyChangeListener() 
+removePropertyChangeListener() 


PropertyChangeEvent event= 
new PropertyChangeEvent(...); 

for each listener (PropertyChangeSupport list): 
listener.propertyChange(event) 


A 
PropertyChangeListener |< --- Y 


+propertyChange() state:datatype 


PropertyChangeEvent 


-eveniState:datatype +propertyChange() 
+getNewValue():Object 
+getOldValue():Object 


+getPropagationName():String 


Figure 2-4. The property change listener Observer pattern 


With a PropertyChangelListener, the registered set of listeners is managed within the 
PropertyChangeSupport class. When the watched property value changes, this support class 
notifies any registered listeners of the new and old property state values. 


Note Although PropertyChangeListener observers are registered at the class level, not all properties 
of the class might be bound. A property is bound when a change to the property causes the registered 
listeners to be notified. In addition, although the JavaBeans framework introduced the concept of property 
change listeners in JDK 1.1, none of the properties of the AWT components were bound, although this changed 
for the Component class in the 1.2 release. The Swing components have many of their properties bound. To 
find out which ones are bound, see the property tables for each Swing component that appear in later chap- 
ters of this book. 
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By registering PropertyChangeListener objects with the various components that support 
this type of listener, you can reduce the amount of source code you must generate after the 
initial listening setup. For instance, the background color of a Swing component is bound, 
meaning someone can register a PropertyChangeListener to a component to be notified when 
the background setting changes. When the value of the background property for that component 
changes, anyone listening is notified, allowing an Observer to change its background color to 
the new setting. Therefore, if you want all the components of your program to have the same 
background color, you can register them all with one component. Then, when that single 
component changes its background color, all the other components will be notified of the 
change and will modify their backgrounds to the new setting. 


Note Although you can use a PropertyChangeListener to “share” a common property setting among 
components, you can also map the property of a subject to a different property of the Observer. 


The program in Listing 2-3 demonstrates using a PropertyChangeListener. It creates two 
buttons. When either button is selected, the background of the selected button is changed to 
some random color. The second button is listening for property changes within the first button. 
When the background color changes for the first button, the background color of the second 
button is changed to that new value. The first button isn't listening for property changes for the 
second button. Therefore, when the second button is selected, changing its background color, 
this change doesn't propagate back to the first button. 


Listing 2-3. Property Change Listener Sample 


import javax.swing.*; 
import java.awt.*; 
import java.awt.event.*; 
import java.beans.*; 
import java.util.Random; 


public class BoundSample ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() £ 
public void run() £ 
JFrame frame = new JFrame("Button Sample"); 
frame.setDefaultClose0peration(JFrame.EXIT_ON CLOSE); 
final JButton button1 = new JButton("Select Me"); 
final JButton button2 = new JButton("No Select Me"); 
final Random random = new Random(); 
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// Define ActionListener 
ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
JButton button = (JButton)actionEvent.getSource(); 
int red = random.nextInt(255); 
int green = random.nextInt(255); 
int blue = random.nextInt(255); 
button.setBackground(new Color(red, green, blue)); 
) 
E 


// Define PropertyChangeListener 
PropertyChangeListener propertyChangeListener = 
new PropertyChangelistener() ( 
public void propertyChange(PropertyChangeEvent propertyChangeEvent) ( 
String property = propertyChangeEvent.getPropertyName(); 
if ("background".equals(property)) ( 
button2.setBackground((Color)propertyChangeEvent.getNewValue()); 
J 
y 
A 


// Attach listeners 
button1.addActionListener(actionListener); 
button1.addPropertyChangeListener(propertyChangeListener); 
button2.addActionListener(actionListener); 


frame.add(button1, BorderLayout.NORTH); 
frame.add(button2, BorderLayout.SOUTH); 
frame.setSize(300, 100); 
frame.setVisible(true); 
) 
y; 
EventQueue.invokeLater(runner); 
) 
) 


Although this example causes only a color change from button selection, imagine ifthe 
background color of the first button could be changed from a couple of hundred different places 
other than the one action listener! Without a property change listener, each of those places 
would be required to also change the background color of the second button. With the property 
change listener, it's only necessary to modify the background color of the primary object—the 
first button, in this case. The change would then automatically propagate to the other components. 

The Swing library also uses the ChangeEvent/ChangeListener pair to signify state changes. 
Although similar to the PropertyChangeEvent/PropertyChangeListener pair, the ChangeEvent 
doesn't carry with it the new and old data value settings. You can think of it as a lighter-weight 
version of a property change listener. The ChangeEvent is useful when more than one property 
value changes, because ChangeEvent doesn't need to package the changes. 
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Tip The Swing components use the SuingPropertyChangeSupport class, instead of the 
PropertyChangeSupport class, to manage and notify their PropertyChangeListener list. The Swing 
version, SwingPropertyChangeSupport, isn't thread-safe, but it is faster and takes up less memory. 
Assuming it is accessed from only the event-dispatch thread, the lack of thread safety ¡is irrelevant. 


Managing Listener Lists 


IHf you're creating your own components and want those components to fire off events, you 
need to maintain a list of listeners to be notified. If the listener list is for AWT events (found in 
java.awt.event), you can use the AWTEventMulticaster class for help with list management. 
Priorto the Swing libraries, ifthe eventwasn't a predefined AWT event type, you had to manage this 
list of listeners yourself. With the help ofthe EventListenerList class in the javax.swing.event 
package, you no longer need to manually manage the listener list and worry about thread 
safety. And, if you ever need to get the list of listeners, you can ask a Component with public 
EventListener[ ] getListeners(Class listenerType), or one of the type-specific methods like 
the getActionListeners() method of JButton. This allows you to remove listeners from an inter- 
nally managed list, which helps with garbage collection. 


AWTEventMulticaster Class 


Whether you realize it or not, the AWTEventMulticaster class is used by each and every AWT 
component to manage event listener lists. The class implements all the AWT event listeners 
(ActionListener, AdjustmentListener, ComponentListener, ContainerListener, FocusListener, 
HierarchyBoundsListener, HierarchyListener, InputMethodListener, ItemListener, KeyListener, 
MouseListener, MouseMotionListener, MousewWheelListener, TextListener, WindowFocusListener, 
WindowListener, and WindowStateListener). Whenever you call a component's method to add 
or remove a listener, the AWTEventMulticaster is used for support. 

If you want to create your own component and manage a list of listeners for one of these 
AWT event/listener pairs, you can use the AWTEventMulticaster. As an example, let's look at 
how to create a generic component that generates an ActionEvent object whenever a key is 
pressed within the component. The component uses the public static String getKeyText 
(int keyCode) method of KeyEvent to convert the key code to its appropriate text string and 
passes this string back as the action command for the ActionEvent. Because the component 
is meant to serve as the source for ActionListener observers, it needs a pair of add/remove 
methods to handle the registration of listeners. This is where the AWTEventMulticaster comes 
in, because it will manage the adding and removing of listeners from your listener list variable: 


private ActionListener actionListenerlist = null; 
public void addActionListener(ActionListener actionListener) f 
actionListenerList = AWTEventMulticaster.add( 
actionListenerList, actionListener); 
) 
public void removeActionListener(ActionListener actionListener) ( 
actionListenerList = AWTEventMulticaster.remove( 
actionListenerList, actionListener); 
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The remainder of the class definition describes how to handle the internal events. An 
internal KeyListener needs to be registered in order to send keystrokes to an ActionListener. 
In addition, the component must be able to get the input focus; otherwise, all keystrokes will 
go to other components. The complete class definition is shown in Listing 2-4. The line of 
source code for notification of the listener list is in boldface. That one line notifies all the regis- 
tered listeners. 


Listing 2-4. Managing Listener Lists with AWTEventMulticaster 


import java.awt.*; 
import java.awt.event.*; 
import javax.swing.*; 


public class KeyTextComponent extends JComponent ( 
private ActionListener actionListenerList = null; 


public KeyTextComponent() ( 
setBackground(Color.CYAN); 
KeyListener internalKeyListener = new KeyAdapter() ( 
public void keyPressed(KeyEvent keyEvent) ( 
if (actionlistenerlist != null) £ 
int keyCode = keyEvent.getKeyCode(); 
String keyText = KeyEvent.getKeyText(keyCode); 
ActionEvent actionEvent = new ActionEvent( 
this, 
ActionEvent.ACTION PERFORMED, 
keyText); 
actionListenerList.actionPerformed(actionEvent); 
J 
J 
A 


MouseListener internalMouseListener = new MouseAdapter() ( 
public void mousePressed(MouseEvent mouseEvent) ( 
requestFocusInWindow(); 
) 
5 


addKeyListener(internalKeyListener); 
addMouseListener(internalMouseListener); 


public void addActionListener(ActionListener actionListener) ( 
actionListenerList = AWTEventMulticaster.add( 
actionListenerList, actionListener); 
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public void removeActionListener(ActionListener actionListener) ( 
actionListenerList = AWTEventMulticaster.remove( 
actionListenerList, actionListener); 


, 


public boolean isFocusable() ( 
return true; 
) 
) 


Figure 2-5 shows the component in use. The top portion of the figure is the component, 
and the bottom is a text field. An ActionListener is registered with the KeyTextComponent that 
updates the text field in order to display the text string for the key pressed. 


[2 key exe sampte A 
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Figure 2-5. Demonstrating the KeyTextComponent 
The source code for the example shown in Figure 2-5 follows in Listing 2-5. 


Listing 2-5. Sample Program with an AWTEventMulticaster Component 


import java.awt.*; 
import java.awt.event.*; 
import javax.swing.*; 


public class KeyTextTester ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() 4 
public void run() £ 

JFrame frame = new JFrame("Key Text Sample"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
KeyTextComponent keyTextComponent = new KeyTextComponent (); 
final JTextField textField = new JTextField(); 


ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
String keyText = actionEvent.getActionCommand(); 
textField.setText(keyText); 
J 
E 
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keyTextComponent.addActionListener(actionListener); 


frame.add(keyTextComponent, BorderLayout.CENTER); 
frame.add(textField, BorderLayout.SOUTH); 
frame.setSize(300, 200); 
frame.setVisible(true); 
) 
5 
EventQueue.invokeLater(runner); 
J 
dE 


EventListenerList Class 


Although the AWTEventMulticaster class is easy to use, it doesn't work for managing lists of 
custom event listeners or any of the Swing event listeners found in javax.swing.event. You 
could create a custom extension of the class for each type of event listener list you need to 
manage (not practical), or you could just store the list in a data structure such as a Vector or 
LinkedList. Although using a Vector or LinkedList works satisfactorily, when you use this method, 
you need to worry about synchronization issues. If you don't program the list management 
properly, the listener notification may happen with the wrong set of listeners. 

To help simplify this situation, the Swing component library includes a special event-listener 
support class, EventListenerList. One instance of the class can manage all the different types 
of event listeners for a component. To demonstrate the class usage, let's see how the previous 
example can be rewritten to use EventListenerList instead of AWTEventMulticaster. Note that 
in this particular example, using the AWTEventMulticaster class is actually the simpler solution. 
However, imagine a similar situation in which the event listener isn't one ofthe predefined 
AWT event listeners or if you need to maintain multiple listener lists. 

The adding and removing of listeners is similar to the technique used with the 
AWTEventMulticaster in the previous example. You need to create a variable of the appropriate 
type—this time EventListenerList—as well as define add and remove listener methods. One 
Key difference between the two approaches is that the initial EventListenerList is non-null, 
whereas the other starts off being null. A reference to an empty EventListenerList must be 
created to start. This removes the need for several checks for a null list variable later. The adding 
and removing of listeners is also slightly different. Because an EventListenerList can manage 
a list of listeners of any type, when you add or remove the listener, you must provide the class 
type for the listener being acted on. 


EventListenerlist actionlListenerlist = new EventListenerList(); 

public void addActionListener(ActionlListener actionListener) ( 
actionListenerlList.add(ActionListener.class, actionListener); 

) 

public void removeActionListener(ActionListener actionListener) ( 
actionListenerlList.remove(ActionListener.class, actionListener); 


J 
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This leaves only the notification of the listeners to be handled. No generic method exists in 
the class to notify all the listeners of a particular type that an event has happened, so you must 
create the code yourself. A call to the following code (fireActionPerformed(actionEvent)) will 
replace the one line of boldfaced source code: 


(actionListenerList.actionPerformed(actionEvent) 


from the previous example. The code gets a copy of all the listeners ofa particular type from the 
list as an array (in a thread-safe manner). You then need to loop through the list and notify the 
appropriate listeners. 


protected void fireActionPerformed(ActionEvent actionEvent) ( 
EventListener listenerlist[] = 
actionListenerList.getListeners(Actionlistener.class); 
for (int i=0, n=listenerlist.length; i<n; i++) ( 
((ActionListener)listenerList[i]).actionPerformed(actionEvent); 
) 
) 


The complete source for the new and improved class follows in Listing 2-6. When using the 
EventListenerList class, don't forget that the class is in the javax. swing .event package. Other 
than the component class name, the testing program doesn't change. 


Listing 2-6. Managing Listener Lists with EventListenerList 


import java.awt.*; 

import java.awt.event.*; 
import javax.swing.*; 

import javax.swing.event.*; 
import java.util.EventListener; 


public class KeyTextComponent2 extends JComponent ( 
private EventListenerList actionListenerList = new EventListenerList(); 


public KeyTextComponent2() ( 
setBackground(Color.CYAN) ; 
KeyListener internalKeyListener = new KeyAdapter() ( 
public void keyPressed(KeyEvent keyEvent) ( 
if (actionlListenerlist != null) € 
int keyCode = keyEvent.getKeyCode(); 
String keyText = KeyEvent.getKeyText(keyCode); 
ActionEvent actionEvent = new ActionEvent( 
this, 
ActionEvent.ACTION PERFORMED, 
keyText); 
fireActionPerformed(actionEvent); 
y 
J 
A 
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MouseListener internalMouseListener = new MouseAdapter() ( 
public void mousePressed(MouseEvent mouseEvent) ( 
requestFocusInWindow(); 
) 
5 


addKeyListener(internalKeyListener); 
addMouseListener(internalMouseListener); 


public void addActionListener(ActionListener actionListener) f 
actionListenerList.add(ActionListener.class, actionListener); 

) 

public void removeActionListener(ActionListener actionListener) ( 
actionListenerList.remove(ActionListener.class, actionListener); 


J 


protected void fireActionPerformed(ActionEvent actionEvent) ( 
EventListener listenerList[] = 
actionlListenerList.getListeners(Actionlistener.class); 
for (int i=0, n=listenerlist.length; i<n; i++) ( 
((ActionListener)listenerList[i]).actionPerformed(actionEvent); 
3 
hi 


public boolean isFocusable() 1 
return true; 
) 
) 


Timer Class 


In addition to the invokeAndWait() and invokeLater() methods of EventQueue, you can use the 
Timer class to create actions to be executed on the event-dispatch thread. A Timer provides a 
way of notifying an ActionListener after a predefined number of milliseconds. The timer can 
repeatedly notify the listeners, or just call them once. 


Creating Timer Objects 


Following is the single constructor for creating a Timer that specifies the millisecond delay time 
between calls to the ActionListener: 


public Timer(int delay, ActionListener actionListener); 
// 1 second interval 
Timer timer = new Timer(1000, anActionListener); 
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Using Timer Objects 


After a Timer object has been created, you need to start() it. Once the Timer is started, the 
ActionListener will be notified after the given number of milliseconds. If the system is busy, 
the delay could be longer, but it won't be shorter. 

If there comes a time when you want to stop a Timer, call its stop() method. The Timer also 
has a restart() method, which calls stop() and start(), restarting the delay period. 

To demonstrate, Listing 2-7 defines an ActionListener that simply prints a message. You 
then create a Timer to call this listener every half second. After creating the timer, you need to 
start it. 


Listing 2-7. Swing Timer Sample 


import javax.swing.*; 
import java.awt.*; 
import java.awt.event.*; 


public class TimerSample ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() 4 
public void run() £ 
ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
System.out.println("Hello World Timer"); 
) 
E 
Timer timer = new Timer(500, actionListener); 
timer.start(); 
) 
5 
EventQueue.invokelLater(runner); 
) 
) 


Note A Timer doesn't start up the AWT event-dispatch thread on its own. 


Timer Properties 


Table 2-1 lists the six properties of Timer. Four allow you to customize the behavior ofthe timer. 
running tells you if a timer has been started but not stopped, and actionListeners gets you the 
list of action listeners. 
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Table 2-1. Timer Properties 


Property Name Data Type Access 

actionListeners ActionListener[ ] Read-only 
coalesce boolean Read-write 
delay int Read-write 
initialDelay int Read-write 
repeats boolean Read-write 
running boolean Read-only 


The delay property is the same as the constructor argument. Ifyou change the delay of a 
running timer, the new delay won't be used until the existing delay runs out. 

The initialDelay property allows you to have another startup delay besides the periodic 
delay after the first execution. For instance, if you don't want to initially do a task for an hour, 
but then want to do it every 15 minutes thereafter, you need to change the initialDelay setting 
before you start the timer. By default, the initialDelay and delay properties are set to the same 
setting in the constructor. 

The repeats property is true by default, which results in a repeating timer. When false, 
the timer notifies action listeners only once. You then need to restart () the timer to trigger the 
listener again. Nonrepeating timers are good for onetime notifications that need to happen 
after a triggering event. 

The coalesce property allows for a busy system to throw away notifications that haven't 
happened yet when a new event needs to be fired to the registered ActionListener objects. By 
default, the coalesce value is true. This means if a timer runs every 500 milliseconds, but its 
system is bogged down and doesn't respond for a whole 2 seconds, the timer needs to send 
only one message, rather than also sending the missing ones. Ifthe setting were false, four 
messages would still need to be sent. 

In addition to the properties just listed, you can turn on log messages with the following 
line of code: 


Timer.setLogTimers(true); 


Log messages are good for actions that lack a visual element, allowing you to see when 
something happens. 


Tip The java. util. Timer class works in a fashion similar to the javax. swing. Timer class, except that 
it doesn't run the scheduled task in the event-dispatch thread. In addition, it supports executing tasks at a 
fixed rate, versus after a fixed delay. The latter scheme permits the repeat rate to drift between executions if 
the event-dispatch thread is busy. 
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Swing-Specific Event Handling 


Keeping in mind that the Swing components are built on top ofthe AWT libraries, the Swing 
component library has several improved capabilities to make event handling much easier. The 
capabilities improve on several of AWT's core event-handling features, from basic action listening 
to focus management. 

To simplify event handling, the Swing library extends the original ActionListener interface 
with the Action interface to store visual attributes with the event handler. This allows the creation 
of event handlers independent of visual components. Then, when the Actionis later associated 
with a component, the component automatically gets information (such as a button label) 
directly from the event handler. This includes notification of updates for the label when the 
Action is modified. The AbstractAction and TextAction classes are implementations of this 
concept. 

The Swing library also adds a KeyStroke class that allows you to more easily respond to key 
events. Instead of watching all key events for a specific key, you can tell a component that when 
a specific keystroke sequence is pressed, it must respond with a particular action. These 
keystroke-to-action mappings are stored in a combination of InputMap and ActionMap objects. 
The InputMap is specifically a Component InputMap when the component's window has the focus. The 
Swing text components can use these more readily to store the mapping of keystrokes to actions 
with the help of the Keymap interface. The mappings for the TextAction support are described 
in more detail in Chapter 16, along with the remainder of the text event-handling capabilities. 

The KeyboardFocusManager and DefaultKeyboardFocusManager, along with the help ofthe 
FocusTraversalPolicy and its implementations, manage the focus subsystem. The InputVerifier 
helps, too, for validation of user input. These are discussed in the “Swing Focus Management” 
section later in this chapter. 


Action Interface 


The Action interface is an extension to the ActionListener interface that's very flexible for 
defining shared event handlers independent of the components that act as the triggering agents. 
The interface implements ActionListener and defines a lookup table data structure whose 
keys act as bound properties. Then, when an Action is associated with a component, these 
display properties are automatically carried over to it. The following is the interface definition: 


public interface Action implements ActionListener ( 
// Constants 
public final static String ACCELERATOR_KEY; 
public final static String ACTION COMMAND KEY; 
public final static String DEFAULT; 
public final static String LONG_DESCRIPTION; 
public final static String MNEMONIC_KEY; 
public final static String NAME; 
public final static String SHORT_DESCRIPTION; 
public final static String SMALL_ICON; 
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// Listeners 

public void addPropertyChangeListener(PropertyChangeListener listener); 
public void removePropertyChangelistener(PropertyChangelistener listener); 
// Properties 

public boolean isEnabled(); 

public void setEnabled(boolean newValue); 

// Other methods 

public Object getValue(String key); 

public void putValue(String key, Object value); 


Because Action is merely an interface, the Swing libraries offer a class to implement the 
interface. That class is AbstractAction. 


AbstractAction Class 


The AbstractAction class provides a default implementation of the Action interface. This is 
where the bound property behavior is implemented. 


Using Actions 


Once you define an AbstractAction by subclassing and providing a public void actionPerformed 
(ActionEvent actionEvent) method, you can then pass it along to some special Swing compo- 
nents. JButton, JCheckBox, JRadioButton, JToggleButton, JMenultem, JCheckBoxMenuTtem, and 
JRadioButtonMenultem provide constructors for creating the components from actions, whereas 
the Swing text components have their own built-in support for Action objects through their 
Keymap, InputMap, and ActionMap 

When the component with the associated Action is added to the respective Swing container, 
selection triggers the calling of the actionPerformed(ActionEvent actionEvent) method ofthe 
Action. The display of the component is defined by the property elements added to the internal 
data structure. To demonstrate, Listing 2-8 presents an Action with a “Print” label and an 
image icon. When this is activated, a “Hello, World” message is printed. 


Listing 2-8. Action Usage Example 


import java.awt.event.*; 
import javax.swing.*; 


public class PrintHelloAction extends AbstractAction ( 

private static final Icon printlcon = new Imagelcon("Print.gif"); 

PrintHelloAction() f 
super("Print", printIcon); 
putValue(Action.SHORT_ DESCRIPTION, "Hello, World"); 

J 

public void actionPerformed(ActionEvent actionEvent) ( 
System.out.println("Hello, World"); 

J 
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Once the Action has been defined, you can create the Action and associate it with as many 
other components as you want. 


Action printAction = new PrintHelloAction(); 
menu.add(new JMenuItem(printAction)); 
toolbar.add(new JButton(printAction)); 


After the Action has been associated with the various objects, if you find that you need to 
modify the properties of the Action, you need to change the setting in only one place. Because 
the properties are all bound, they propagate to any component that uses the Action. For instance, 
disabling the Action (printAction.setEnabled(false)) will disable the JMenuTtem and JButton 
created on the JMenu and JToo1Bar, respectively. In contrast, changing the name of the Action 
with printAction.putValue(Action.NAME, "Hello, World") changes the text label of the asso- 
ciated components. 

Figure 2-6 shows what the PrintHelloAction might look like on a JToo1Bar and a JMenu. 
Selectable buttons are provided to enable or disable the Action, as well as to change its name. 
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Figure 2-6. The PrintHelloAction in use 


The complete source code for this example follows in Listing 2-9. Don't worry just yet 
about the specifics of creating toolbars and menu bars. They”Il be discussed in more detail 
in Chapter 6. 


Listing 2-9. PrintHelloAction Example 


import java.awt.*; 
import java.awt.event.*; 
import javax.swing.*; 


public class ActionTester ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() £ 
public void run() £ 
JFrame frame = new JFrame("Action Sample"); 
frame.setDefaultClose0peration(JFrame.EXIT_ON CLOSE); 
final Action printAction = new PrintHelloAction(); 


JMenuBar menuBar = new JMenuBar(); 
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JMenu menu = new JMenu("File"); 
enuBar.add(menu) ; 
enu.add(new JMenultem(printAction)); 


JToolBar toolbar = new JTool1Bar(); 
toolbar.add(new JButton(printAction)); 


JButton enableButton = new JButton("Enable"); 
ActionListener enableActionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
printAction.setEnabled(true); 
y 
E 


enableButton.addActionListener(enableActionListener); 


JButton disableButton = new JButton("Disable"); 
ActionListener disableActionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
printAction.setEnabled(false); 
y 
E 


disableButton.addActionListener(disableActionListener); 


JButton relabelButton = new JButton("Relabel"); 
ActionlListener relabelActionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
printAction.putValue(Action.NAME, "Hello, World"); 
y 
5 


relabelButton.addActionListener(relabelActionListener); 


JPanel buttonPanel = new JPanel(); 
buttonPanel.add(enableButton); 
buttonPanel.add(disableButton); 
buttonPanel.add(relabelButton); 


frame.setJMenuBar(menuBar) ; 


frame.add(toolbar, BorderLayout.SOUTH); 
frame.add(buttonPanel, BorderLayout.NORTH); 
frame.setSize(300, 200); 
frame.setVisible(true); 
h 
E 
EventQueue.invokeLater(runner); 
J 
) 
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AbstractAction Properties 


As Table 2-2 shows, the AbstractAction class has three available properties. 


Table 2-2. AbstractAction Properties 


Property Name Data Type Access 
enabled boolean... Read=writebound 
keys Object [ ] Read-only 
propertyChangeListeners PropertyChangelistener[ ] Read-only 


The remainder of the bound properties are placed in the lookup table with putValue 
(String key, Object value). Getting the current keys property setting allows you to find out 
which ones can be seten masse, instead of asking for each one individually. Table 2-3 describes 
the predefined set of Action constants that can be used as the key. You can also add your own 
constants, to look up later when the action happens. 


Table 2-3. AbstractAction Lookup Property Keys 


Constant Description 

NAME Action name, used as button label 

SMALL_TCON Icon for the Action, used as button label 

SHORT_DESCRIPTION Short description of the Action; could be used as tooltip text, but 
not by default 

LONG_DESCRIPTION Long description of the Action; could be used for accessibility 
(see Chapter 22) 

ACCELERATOR KeyStroke string; can be used as the accelerator for the Action 

ACTION COMMAND KEY InputMap key; maps to the Action in the ActionMap of the associ- 
ated JComponent 

MNEMONIC_KEY Key code; can be used as mnemonic for action 

DEFAULT Unused constant that could be used for your own property 


Once a property has been placed in the lookup table, you can get it with public Object 
getValue(String key). It works similarly to the java.util.Hashtable class or java.util.Map 
interface, with one distinction: ifyou try to put a key/value pair into the table with a null value, 
the table removes the key, if it's present. 


KeyStroke Class 


The KeyStroke class and the inputMap and actionMap properties of a specific JComponent provide 
a simple replacement for registering KeyListener objects to components and watching for 


4 
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specific keys to be pressed. The KeyStroke class allows you to define a single combination of 
keystrokes, such as Shift-Ctrl-P or F4. You can then activate the keystroke by registering it with 
a component and telling the keystroke what to do when the component recognizes it, causing 
the ActionListener to be notified. 

Before finding out how to create keystrokes, let's look at the different conditions that can 
be activated and thus added to different input maps. Three conditions can activate a registered 
Keystroke, and there are four constants in JComponent to help. The fourth is for an undefined 
state. The four available constants are listed in Table 2-4. 


Table 2-4. Keystroke Registration Conditions 


Constant Description 


WHEN_FOCUSED Activates the keystroke when the actual component 
has the input focus 


WHEN_TN_FOCUSED WINDOW Activates the keystroke when the window that the 
component is in has the input focus 


WHEN_ANCESTOR_OF_FOCUSED COMPONENT  Activates the keystroke when pressed in the component 
or a container of the component 


UNDEFINED CONDITION For when no condition is defined 


Note In the special instance in which the keystrokes are supposed to be active only when the component 
is in the focused window, the InputMap is actually a Component InputMap. 


Creating a KeyStroke 


The KeyStroke class is a subclass of AWTKeyStroke and has no public constructor. You create a 
keystroke by using one of the following methods: 


public static KeyStroke getKeyStroke(char keyChar) 

public static KeyStroke getKeyStroke(String representation) 

public static KeyStroke getKeyStroke(int keyCode, int modifiers) 

public static KeyStroke getKeyStroke(int keyCode, int modifiers, 
boolean onKeyRelease) 

public static KeyStroke getKeyStrokeForEvent(KeyEvent keyEvent) 


The first version in this list, public static KeyStroke getKeyStroke(char keyChar), allows 
you to create a keystroke from a char variable, such as Z. 


KeyStroke space = KeyStroke.getKeyStroke('Z'); 
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Note | prefer to avoid using a char variable to create a keystroke, because you don't know whether to 
specify an uppercase or lowercase letter. There is also an outdated, or deprecated, version of this method that 
adds a boolean onKeyRelease argument. This, too, should be avoided. 


The public static KeyStroke getKeyStroke(String representation) version is the most 
interesting of the lot. It allows you to specify a keystroke as a text string, such as "control F4". 
The set of modifiers to the string are shift, control, meta, alt, button1, button2, and button3, 
and multiple modifiers can be specified. The remainder of the string comes from one ofthe 
many VK_* constants of the KeyEvent class. For example, the following defines a keystroke for 
Ctrl-Alt-7: 


KeyStroke controlA1t7 = KeyStroke.getKeyStroke("control alt 7"); 


The public static KeyStroke getKeyStroke(int keyCode, int modifiers) and public 
static KeyStroke getKeyStroke(int keyCode, int modifiers, boolean onKeyRelease) 
methods are the most straightforward. They allow you to directly specify the VK_* key constant 
and the InputEvent masks for the modifiers (or zero for no modifiers). When not specified, 
onKeyRelease is false. 


KeyStroke enter = KeyStroke.getKeyStroke(KeyEvent.VK_ENTER, O, true); 
KeyStroke shiftF4 = KeyStroke.getKeyStroke(KeyEvent.VK_F4, InputEvent.SHIFT_MASK); 


The last version listed, public static KeyStroke getKeyStrokeForEvent(KeyEvent keyEvent), 
maps a specific KeyEvent directly to a KeyStroke. This is useful when you want to allow a user to 
supply the keystroke to activate an event. You ask the user to press a key for the event, and then 
register the KeyEvent so that the next time it happens, the event is activated. 


KeyStroke fromKeyEvent = KeyStroke.getKeyStrokeForEvent(keyEvent); 


Registering a KeyStroke 


After you've created the keystroke, you need to register it with a component. When you register 
a keystroke with a component, you provide an Action to call when pressed (or released). Regis- 
tration involves providing a mapping from keystroke to Action. First, you get the appropriate 
InputMap for the component based on the focus activation condition (from Table 2-4) with 
getInputMap(condition). Ifno condition is provided, WNHEN_FOCUSED is assumed. You then add a 
mapping from keystroke to text string in the InputMap: 


component .getInputMap().put(keystroke, string) 


Il you know the action string for an existing action, you can use that; otherwise, you define 
the string. You then work with the ActionMap to map that string to an Action: 


component .getActionMap.put(string, action) 
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You can share actions between components by sharing ActionMap instances. The example 


in Listing 2-10 creates four buttons, each with a different keystroke registered to it and possibly 
a different focus-activation condition, as listed in Table 2-4. The button label signifies the 
keystroke-activation conditions. The Action simply prints out a message and the activating 
button label. 


Listing 2-10. KeyStroke Listening 


im 
im 
im 


pu 


port javax.swing.*; 
port java.awt.*; 
port java.awt.event.*; 


blic class KeyStrokeSample ( 

private static final String ACTION_KEY 

public static void main(String args[]) 

Runnable runner = new Runnable() f 
public void run() ( 


"theAction"; 


( 


JFrame frame = new JFrame("KeyStroke Sample"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


JButton buttonA = 

new JButton("<html><center>FOCUSED<br>control alt 7"); 
JButton buttonB = 
new JButton("<html><center>FOCUS/RELEASE<br>VK_ENTER"); 
JButton buttonC = 
new JButton("<html><center>ANCESTOR<br>VK_F4+SHIFT_MASK"); 
JButton buttonD = 
new JButton("<html><center>WINDOW<br>' '"); 


// Define ActionListener 
Action actionListener = new AbstractAction() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
JButton source = (JButton)actionEvent.getSource(); 
System.out.println("Activated: " + source.getText()); 
) 
E 


KeyStroke controlA1t7 = KeyStroke.getKeyStroke("control alt 7"); 
InputMap inputMap = buttonA.getInputMap(); 
inputMap.put(controlA1t7, ACTION KEY); 

ActionMap actionMap = buttonA.getActionMap(); 
actionMap.put(ACTION KEY, actionListener); 


KeyStroke enter = KeyStroke.getKeyStroke(KeyEvent.VK_ENTER, O, true); 
inputMap = buttonB.getInputMap(); 
inputMap.put(enter, ACTION KEY); 
buttonB.setActionMap(actionMap); 
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KeyStroke shiftF4 = 

KeyStroke.getKeyStroke(KeyEvent.VK_F4, InputEvent.SHIFT_MASK); 
inputMap = 

buttonC.getInputMap(JComponent .WHEN_ANCESTOR_OF_FOCUSED_ COMPONENT) ; 
inputMap.put(shiftF4, ACTION KEY); 
buttonC.setActionMap(actionMap); 


KeyStroke space = KeyStroke.getKeyStroke(' '); 

inputMap = buttonD.getInputMap(JComponent.WHEN_IN_FOCUSED WINDOW) ; 
inputMap.put(space, ACTION KEY); 

buttonD.setActionMap(actionMap); 


frame.setLayout(new GridLayout(2,2)); 
frame.add(buttonA); 
frame.add(buttonB) ; 
frame.add(buttonC); 
frame.add(buttonD) ; 
frame.setSize(400, 200); 
frame.setVisible(true); 
J 
5 


EventQueue.invokeLater(runner); 


y 
, 


Tip For text components, you can get the Keymap and bind an Action to a KeyStroke in one step with 
addActionForKeyStroke(KeyStroke, Action). 


Figure 2-7 shows what the running program looks like. 


[> keystroresomne A 


FOCUSED 
control alt 7 


ANCESTOR 
VK_F4+SHIFT_MASK 


FOCUS/RELEASE 
WK_ENTER 


Figure 2-7. KeyStroke listening example 
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Using Mnemonics and Accelerators 


The Swing libraries also use KeyStroke objects for several internal functions. Two such functions 
are component mnemonics and accelerators, which work as follows: 


+ Ina component mnemonic, one character in a label appears underlined. When that 
character is pressed along with a platform-specific hotkey combination, the component 
is activated. Forinstance, pressing Alt-A in the window shown in Figure 2-8 would select 
the About button on a Windows XP platform. 


+ A menu accelerator activates a menu item when it is not visible. For instance, pressing 
Ctrl-P would select the Print menu item in the window shown in Figure 2-8 when the File 
menu isn't visible. 


£. Mnemonic/Accelerator $ 101 x] 
File 
Print_ct 
About 
Accelerator 
Mnemonic 


Figure 2-8. Mnemonics and menu shortcuts 


You'll learn more about mnemonics and accelerators in Chapter 6. 


Swing Focus Management 


The term focus refers to when a component acquires the input focus. When a component has 
the input focus, it serves as the source for all key events, such as text input. In addition, certain 
components have some visual markings to indicate that they have the input focus, as shown in 
Figure 2-9. When certain components have the input focus, you can trigger selection with a 
keyboard key (usually the spacebar or Enter key), in addition to selection with a mouse. For 
instance, with a button, pressing the spacebar activates it. 


la xi 
Focus Highlight AS ES Not Focused 


Figure 2-9. A JButton showing it has input focus 
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Note The focus subsystem had a major overhaul with the 1.4 release of J2SE. All the older guts are still 
present, but should be avoided. The older stuff didn't work well and was very buggy. Sun's fix was to essen- 
tially throw everything away and start over, but old APIs are still present. In your quest to work with the focus 
subsystem, learn to use only the updated APIs, not the older ones. Classes like javax. swing. FocusManager 
and javax.swing.DefaultFocusManager are completely obsolete now. 


An important concept in focus management is the focus cycle, which maps the focus traversal 
order for the closed set of components within a specific Container. The following classes are 
also major players in focus management: 


+ FocusTraversalPolicy: A java. awt class that defines the algorithm used to determine the 
next and previous focusable components. 


+ KeyboardFocusManager: A java. awt class that acts as the controller for keyboard navigation 
and focus changes. To request a focus change, you tell the manager to change focusable 
components; you don't request focus on a particular component. 


You can find out when the Swing component gets the input focus by registering a 
FocusListener. The listener allows you to find out when a component gains or loses focus, 
which component lost focus when another component gained it, and which component got 
focus when another component lost focus. Additionally, a temporary focus change can happen 
for something like a pop-up menu. The component that lost focus will receive it again when 
the menu goes down. 

The installed focus traversal policy describes how to move between the focusable compo- 
nents of a window. By default, the next componentis defined by the order in which components 
are added to a container, as shown in Figure 2-10. For Swing applications, this focus traversal 
starts at the top left of the figure and goes across each row and down to the bottom right. This is the 
default policy, LayoutFocusTraversalPolicy. When all the components are in the same container, 
this traversal order is called a focus cycle and can be limited to remain within that container. 


Note A user can press Tab or Shift-Tab to move forward or backward through the components in a 
container, thus transferring the input focus. 
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a 


a a 


Figure 2-10. Default focus ordering 


Moving the Focus 


As an example of some basic capabilities, let's look at how to create two listeners to handle 
input focus: a MouseListener that moves the input focus to a component when the mouse 
enters its space, and an ActionListener that transfers the input focus to the next component. 

The MouseListener merely needs to call requestFocusInWindow() when the mouse enters 
the component. 


import java.awt.*; 
import java.awt.event.*; 
public class MouseEnterFocusMover extends MouseAdapter f 
public void mouseEntered(MouseEvent mouseEvent) ( 
Component component = mouseEvent.getComponent (); 
if (!component.hasFocus()) 4 
component .requestFocusInWindow(); 
J 
J 
y 


For the ActionListener, you need to call the focusNextComponent () method for the 
KeyboardFocusManager. 


import java.awt.*; 
import java.awt.event.*; 
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public class ActionFocusMover implements ActionListener ( 
public void actionPerformed(ActionEvent actionEvent) ( 
KeyboardFocusManager manager = 
KeyboardFocusManager.getCurrentKeyboardFocusManager (>; 
manager. focusNextComponent (); 
y 
J 


The ActionFocusMover and MouseEnterFocusMover show two different ways of programmati- 
cally moving focus around. The ActionFocusMover uses the KeyboardFocusManager for traversal. 
In MouseEnterFocusMover, the call to requestFocusInWindow() says that you would like for the 
suggested component to get focus for the window of the application. However, getting focus 
can be turned off. Ifthe component isn't focusable, either because the default setting ofthe 
focusable property is false or you called component. setFocusable(false), then the component 
will be skipped over and the next component after it gets focus; the component is removed 
from the tab focus cycle. (Think of a scrollbar that isn't in the focus cycle, but is draggable to 
change a setting.) 

The program in Listing 2-11 uses the two event handlers for moving focus around. It creates a 
3x3 grid of buttons, in which each button has an attached mouse listener and a focus listener. 
The even buttons are selectable but aren't focusable. 


Listing 2-11. Focus Traversal Sample 


import javax.swing.*; 
import java.awt.*; 
import java.awt.event.*; 


public class FocusSample ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() £ 
public void run() £ 
JFrame frame = new JFrame("Focus Sample"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


ActionListener actionListener = new ActionFocusMover(); 
MouseListener mouseListener = new MouseEnterFocusMover(); 


frame.setLayout(new GridLayout(3,3)); 
for (int i=1; 1<10; i++) ( 
JButton button = new JButton(Integer.toString(i)); 
button.addActionListener(actionListener); 
button.addMouseListener(mouseListener); 
if ((1%2) != 0) £ // odd - enabled by default 
button.setFocusable(false); 


) 
frame.add(button); 
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frame.setSize(300, 200); 
frame.setVisible(true); 
4 
5 
Event0Queue.invokeLater(runner); 
y 
y 


Figure 2-11 shows the main window of the program. 


Figure 2-11. Focus management example 


Examining Focus Cycles 


One customization option available at the Swing container level is the focus cycle. Remember 
that the focus cycle for a container is a map of the focus traversal order for the closed set of 
components. You can limit the focus cycle to stay within the bounds of a container by setting 
the focusCycleRoot property to be true, thus restricting the focus traversal from going beyond 
an inner container. Then, when the Tab key is pressed within the last component of the container, 
the focus cycle will wrap back to the first component in the container, instead of moving the 
input focus to the first component outside the container. When Shift-Tab is pressed in the first 
component, it wraps to the last component ofthe container, instead ofto the prior component 
in the outer container. 

Figure 2-12 illustrates how the focus ordering would look if you placed the middle three 
buttons from Figure 2-10 within a container restricted in this way. In this cycle, you cannot get 
to the first component on the third row by pressing the Tab key to move forward. To be able to 
tab into the second row container, you need to setthe focusTraversalPolicyProvider property 
to true. Otherwise, while the panel will keep the traversal policywithin the second row, tabbingwill 
never get you into the third row. 
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a 
a 


a 


Figure 2-12. Restrictive focus cycle 


a 


(e 


The program in Listing 2-12 demonstrates the behavior illustrated in Figure 2-12. The 
on-screen program will look just like Figure 2-11; it just behaves differently. 


Listing 2-12. Restricting the Focus Cycle 


import javax.swing. 
import java.awt.*; 


ko 
, 


import java.awt.event.*; 


public class FocusCycleSample ( 


public static void main(String args[]) ( 
Runnable runner = new Runnable() 4 

public void run() £ 
JFrame frame = new JFrame("Focus Cycle Sample"); 

frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


frame.setLayout(new GridBagLayout()); 
GridBagConstraints constraints = new GridBagConstraints(); 


constraints 
constraints 
constraints 
constraints 
constraints 


.weightx 
.weighty 
.gridwidth 
.gridheight 
FULL 


= 1.0; 
= 1.0; 

= 1; 

1; 
GridBagConstraints.BOTH; 


51 


52 CHAPTER 2 EVENT HANDLING WITH THE SWING COMPONENT SET 


// Row One 

constraints.gridy=0; 

for (int i=0; 1<3; i++) ( 
JButton button = new JButton("" + 1); 
constraints.gridx=i; 
frame.add(button, constraints); 


J 


// Row Two 
JPanel panel = new JPanel(); 
panel.setFocusCycleRoot (true); 
panel.setFocusTraversalPolicyProvider (true); 
panel.setLayout(new GridLayout(1,3)); 
for (int i=0; 1<3; i++) ( 
JButton button = new JButton("" + (1+3)); 
panel.add(button); 
) 
constraints.gridx=0; 
constraints.gridy=1; 
constraints.gridwidth=3; 
frame.add(panel, constraints); 


// Row Three 
constraints.gridy=2; 
constraints.gridwidth=1; 
for (int i=0; 1<3; i++) ( 
JButton button = new JButton("" + (1+6)); 
constraints.gridx=i; 
frame.add(button, constraints); 


y 


frame.setSize(300, 200); 
frame.setVisible(true); 
) 
5 
EventQueue.invokeLater(runner); 
) 
) 


FocusTraversalPolicy Class 


The FocusTraversalPolicy is responsible for determining the focus traversal order. It allows 
you to specify the next and previous components in the order. This class offers six methods for 
controlling traversal order: 
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» getComponentAfter(Container aContainer, Component aComponent) 
» getComponentBefore(Container aContainer, Component aComponent) 
» getDefaultComponent(Container aContainer) 

+ getFirstComponent (Container aContainer) 

+ getInitialComponent(Window window) 

+ getLastComponent(Container aContainer) 


Swing provides five predefined traversal policies, as listed in Table 2-5. By picking the right 
traversal policy for your application, or rolling your own, you can determine how users will 
navigate around the screens. 


Table 2-5. Predefined Traversal Policies 


Policy Description 


ContainerOrderFocusTraversalPolicy The components are traversed in the order they are 
added to their container. The component must be 
visible, displayable, enabled, and focusable to be 
part of the focus cycle. 


DefaultFocusTraversalPolicy The default policy for AWT programs, this extends 
ContainerOrderFocusTraversalPolicy to check 
with the component peer (the operating system) if 
the component hasn't explicitly set focusability. 
The focusability of a peer depends on the Java 
runtime implementation. 


InternalFrameFocusTraversalPolicy Special policy for JInternalFrame, with behavior to 
determine initial focusable component based on 
the default component of the frame. 


SortingFocusTraversalPolicy Here, you provide a Comparator to the policy 
constructor to define the focus cycle order. 


LayoutFocusTraversalPolicy The default policy for Swing programs, this takes 
into account geometric settings of components 
(height, width, position), and then goes top down, 
left to right to determine navigation order. The top- 
down, left-right order is determined by the current 
ComponentOrientation setting for your locale. For 
instance, Hebrew would be in right-left order instead. 


To demonstrate, the program in Listing 2-13 reverses the functionality of Tab and Shift- 
Tab. When you run the program, it looks the same as the screen shown earlier in Figure 2-11, 
with the 3x3 set of buttons. However, with this version, the initial focus starts on the 9 button, 
and pressing Tab takes you to 8, then 7, and so on. Shift-Tab goes in the other, more normal, 
order. 
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Listing 2-13. Reversing Focus Traversal 


import javax.swing.*; 

import java.awt.*; 

import java.awt.event.*; 
import java.util.Comparator; 
import java.util.Arrays; 
import java.util.List; 


public class NextComponentSample ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("Reverse Sample"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


frame.setLayout(new GridLayout(3,3)); 

// for (int i=1; i<10; i++) £ 

for (int i=9; 1>0; i--) ( 
JButton button = new JButton(Integer.toString(i)); 
frame.add(button, 0); 


J 


final Container contentPane = frame.getContentPane(); 
Comparator<Component> comp = new Comparator<Component>() ( 
public int compare(Component c1, Component c2) ( 
Component comps[] = contentPane.getComponents(); 
List list = Arrays.asList(comps); 
int first = list.index0f(c1); 
int second = list.index0f(c2); 
return second - first; 
J 
A 


FocusTraversalPolicy policy = new SortingFocusTraversalPolicy(comp); 
frame.setFocusTraversalPolicy(policy); 


frame.setSize(300, 200); 
frame.setVisible(true); 
) 
E 
EventQueue.invokeLater(runner); 
) 
) 


CHAPTER 2 EVENT HANDLING WITH THE SWING COMPONENT SET 


KeyboardFocusManager Class 


The abstract KeyboardFocusManager class in the AWT library serves as the control mechanism 
framework for the input focus behavior of Swing components. The DefaultKeyboardFocusManager 
is the concrete implementation. The focus manager allows you to both programmatically 
discover who currently has the input focus and to change it. 

The component with the current input focus is called the focus owner. This is accessible 
via the focusOwner property of KeyboardFocusManager. You can also discover the focusedWindow 
and activeWindow properties. The focused window is the window containing the focus owner, and 
the active windows either the focused window or the frame or dialog containing the focus owner. 

The simple concept of moving to the previous or next component is supported in many 
different ways. First, you can use the shortcut API methods of Component and Container: 


+ Component.transferFocus() 

+ Component .transferFocusBackward() 
+ Component .transferFocusUpCycle() 
. Container.transferFocusDownCycle() 


The first two methods request focus to move to the next or previous component, respec- 
tively. The up and down cycle methods request that you move up out of the current focus cycle 
or down into the next cycle. 

The following methods map directly to methods of the KeyboardFocusManager: 


* focusNextComponent () 

» focusPreviousComponent() 
» upFocusCycle() 

» downFocusCycle() 


A second set of the same four methods accepts a second parameter of a Component. Ifthe 
component isn't specified, these methods change the focused component based on the current 
focus owner. Ifa component is provided, the change is based on that component. 

Tab and Shift-Tab are used for keyboard focus traversal because they are defined as the 
default focus traversal keys for most, if not all, components. To define your own traversal keys, 
you can replace or append to a key set via the setFocusTraversalKeys() method of Component. 
Different sets are available for forward, backward, and up-cycle, as specified by the FORWARD 
TRAVERSAL_KEYS, BACKWARD_TRAVERSAL_KEYS, and UP_CYCLE_TRAVERSAL_KEYS constants of 
KeyboardFocusManager. You can set and get key sets for each. For instance, to add the F3 key 
as an up-cycle key for a component, use the following code: 


Set<AWTKeyStroke> set = component .getFocusTraversalKeys( 
KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS); 

KeyStroke stroke = KeyStroket.getKeyStroke("F3"); 

set.add(stroke); 

component .setFocusTraversalKeys(KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS, set); 
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Verifying Input During Focus Traversal 


Swing offers the abstract InputVerifier class for component-level verification during focus 
traversal with any JComponent. Just subclass InputVerifier and provide your own public 
boolean verify(JComponent) method to verify the contents of the component. 

Listing 2-14 provides a simple numeric text field verification example, showing three text 
fields, of which only two have verification. Unless fields one and three are valid, you can't tab 
out ofthem. 


Listing 2-14. Numeric Input Verifier 


import java.awt.*; 
import java.awt.event.*; 
import javax.swing.*; 


public class VerifierSample ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() 4 

JFrame frame = new JFrame("Verifier Sample"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
JTextField textField1 = new JTextField(); 

JTextField textField2 = new JTextField(); 

JTextField textField3 = new JTextField(); 


InputVerifier verifier = new InputVerifier() ( 
public boolean verify(JComponent comp) f 
boolean returnValue; 
JTextField textField = (JTextField)comp; 
tEyÍ 
Integer.parselnt(textField.getText()); 
returnValue = true; 
) catch (NumberFormatException e) ( 
returnValue = false; 
J 
return returnValue; 
) 
E 


textField1.setInputVerifier(verifier); 
textField3.setInputVerifier(verifier); 


frame.add(textField1, BorderLayout.NORTH); 
frame.add(textField2, BorderLayout.CENTER); 
frame.add(textField3, BorderLayout.SOUTH); 
frame.setSize(300, 100); 
frame.setVisible(true); 
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$»; 
EventQueue.invokeLater(runner); 
) 
) 


Tip To make sure that cancel-type buttons get the input focus no matter what when using InputVerifier, 
use the setVerifyInputWhenFocusTarget (false) method with the component. 


Summary 


In this chapter, you looked at the many ways of dealing with event handling when using Swing 
components. Because Swing components are built on top of AWT components, you can use the 
delegation-based event-handling mechanism common with those components. You then learned 
about the multithreading limitations of the Swing components and how to get around them 
with the invokeAndWait() and invokeLater() methods of EventQueue. You also explored how 
the Swing components use the JavaBeans PropertyChangeListener approach for notification of 
bound property changes. 

Besides exploring the similarities between the Swing components and AWT components, 
you also looked at several ofthe new features that the Swing library offers. You explored the 
Action interface and how it can simplify complex user-interface development by completely 
separatingthe event-handling task from the visual component. You looked at the technique for 
registering KeyStroke objects to components to simplify listening for key events. Finally, you 
explored Swing's focus management capabilities and howto customize the focus cycle and use 
the FocusTraversalPolicy and KeyboardFocusManager, as well as validating input with the 
InputVerifier. 

In Chapter 3, you'll meet the Model-View-Controller (MVC) architecture of the Swing 
component set. You'll learn how MVC can make your user interface development efforts 
much easier. 
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CHAPTER 3 


The Model-View-Controller 
Architecture 


a 2 explored how to deal with event producers and consumers with regard to Swing 
components. We looked at how event handling with Swing components goes beyond the 
event-handling capabilities ofthe original AWT components. In this chapter, we will take the 
Swing component design one step further to examine what is called the Model-View-Controller 
(MVOC) architecture. 


Understanding the Flow of MVC 


First introduced in Smalltalk in the late 1980s, the MVC architecture is a special form of the 
Observer pattern described in Chapter 2. The model part of the MVC holds the state of a 
component and serves as the Subject. The view part of the MVC serves as the Observer of the 
Subject to display the model's state. The view creates the controller, which defines how the 
user interface reacts to user input. 


MVC Communication 


Figure 3-1 shows how the MVC elements communicate—in this case, with Swing's multiline 
text component, the JTextArea. In MVC terms, the JTextArea serves as the view part within the 
MVC architecture. Displayed within the component is a Document, which is the model for the 
JTextArea. The Document stores the state information for the JTextArea, such as the text contents. 
Within the JTextArea is the controller, in the form of an InputMap. It maps keyboard input to 
commands in an ActionMap, and those commands are mapped to TextAction objects, which 
can modify the Document. When the modification happens, the Document creates a 
DocumentEvent and sends it back to the JTextArea. 
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AN 
View Model Controller 
JTextArea Document InputMap 


Registers with er 
Receives user input er 


Creates Translates to 
model-level event 


DocumentEvent 
Created 


Sends state change 


Figure 3-1. MVC communication mechanism 


Ul Delegates for Swing Components 


This example demonstrates an important aspect of the MVC architecture within the Swing 
world. Complex interactions need to happen between the view and the controller. The Swing 
design combines these two elements into a delegate object to simplify the overall design. This 
results in each Swing component having a Ul delegate thatis in charge of rendering the current 
state of the component and dealing with user input events. 

Sometimes, the user events result in changes to the view that don't affect the model. For 
instance, the cursor position is an attribute of the view. The model doesn't care about the posi- 
tion of the cursor, only the text contents. User input that affects the cursor position isn't passed 
along to the model. At other times, user input that affects the contents of the Document (for 
example, pressing the Backspace key) is passed along. Pressing the Backspace key results in a 
character being removed from the model. Because of this tight coupling, each Swing component 
has a Ul delegate. 

To demonstrate, Figure 3-2 shows the makeup ofthe JTextArea, with respect to the model 
and UI delegate. The UI delegate for the JTextArea starts with the TextUl interface, with 
its basic implementation in the BasicTextUl class. In turn, this is specialized with the 
BasicTextAreaUI for the JTextArea. The BasicTextAreaUl creates a view that is either a 
PlainView or a WrappedPlainView. On the model side, things are much simpler. The Document 
interface is implemented by the AbstractDocument class, which is further specialized by the 
PlainDocument. 

The text components will be explained more fully in Chapters 15 and 16. As the diagram in 
Figure 3-2 demonstrates, much is involved in working with the text components. In most cases, 
you don't need to deal with the specifics to the degree shown in this figure. However, all of 
these classes are working behind the scenes. The UI-delegate part ofthe MVC architecture will 
be discussed further in Chapter 20, when we explore how to customize delegates. 


Model 


<<Interface>»> 
Document 


| 


¡AbstractDocument) 


| 


PlainDocument 


Figure 3-2. The JTextArea MVC architecture 
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Sharing Data Models 


Because data models store only the state information, you can share a model across multiple 


components. Then each component view can be used to modify the model. 


In the case of Figure 3-3, three different JTextArea components are used to modify one 
Document model. If a user modifies the contents of one JTextArea, the model is changed, 
causing the other text areas to automatically reflect the updated document state. Itisn't necessary 


for any Document view to manually notify others sharing the model. 
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Controller Controller Controller 
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Document 


Figure 3-3. Sharing MVC data models 


Sharing of a data model can be done in either one of two ways: 


+ You can create the data model apart from any component and tell each component to 
use the data model. 


+ You can create one component first, get the model from the first component, and then 
share it with the other components. 


Listing 3-1 demonstrates how to share a data model using the latter technique. 


Listing 3-1. Sharing an MVC Model 


import java.awt.*; 
import javax.swing.*; 
import javax.swing.text.*; 


public class ShareModel ( 
public static void main (String args[]) ( 
Runnable runner = new Runnable() 4 

public void run() 4 
JFrame frame = new JFrame("Sharing Sample"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
Container content = frame.getContentPane(); 
JTextArea textarea1 = new JTextArea(); 
Document document = textarea1.getDocument(); 
JTextArea textarea2 = new JTextArea(document); 
JTextArea textarea3 = new JTextArea(document); 
content .setLayout(new BoxLayout (content, BoxLayout.Y AXIS)); 
content.add(new JScrollPane(textarea1)); 
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content.add(new JScrollPane(textarea2)); 
content.add(new JScrollPane(textarea3)); 
frame.setSize (300, 400); 
frame.setVisible (true); 
) 
$»; 
EventQueue.invokeLater(runner); 
) 
) 


Figure 3-4 shows how this program might look after editing the shared document. Notice 
that the three text areas are capable of viewing (or modifying) different areas ofthe document. 
They aren't limited to adding text only at the end, for instance. This is because each text area 
manages the position and cursor separately. The position and cursor are attributes of the view, 
not the model. 


£ Sharing Sample =10/x/ 
import java.awt*; = 


import javax.swing.*; 
import javax.swing.text.*; 


public class ShareModel ( 
public static void main (String args[) £ 
hblarunnar= na PBunnablaós 
4 T |» 
funnable runner= new Runnable( £ el 
public void runó 4 pis] 
JFrame frame = new JFrame('Sharing Sample")¡|= 
frame.setDefaultCloseOperationíJFrame.EXIT_ 
Container content= frame. getContentPane(); 
JTextArea textareal = new JTextArea(; 


4] T |» 


J y 


) 


EventQueue invokeLater(runner); 


Figure 3-4. Sharing a document between JTextArea components 


Understanding the Predefined Data Models 


When working with Swing components, it's helpful to understand the data models behind 
each of the components because the data models store their state. Understanding the data 
model for each component helps you to separate the parts ofthe component that are visual 
(and thus part of the view) from those that are logical (and thus part of the data model). For 
example, by understanding this separation, you can see why the cursor position within a 
JTextArea isn't part of the data model, but rather is part of the view. 

Table 3-1 provides a complete listing of the Swing components, the interface that describes 
the data model for each component, as well as the specific implementations. Ifa component 
isn't listed, that component inherits its data model from its parent class, most likely 
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AbstractButton. In addition, in some cases, multiple interfaces are used to describe a compo- 
nent, because the data is stored in one model and the selection ofthe data is in a second model. 
In the case of the JComboBox, the MutableComboBoxModel interface extends from ComboBoxModel. 
No predefined class implements the ComboBoxModel interface without also implementing the 
MutableComboBoxModel interface. 


Table 3-1. Swing Component Models 


Component Data Model Interface Implementations 
AbstractButton ButtonModel DefaultButtonModel 
JColorChooser ColorSelectionModel DefaultColorSelectionModel 
JComboBox ComboBoxModel N/A 
MutableComboBoxModel DefaultComboBoxModel 
JFileChooser ListModel BasicDirectoryModel 
JList ListModel AbstractListModel 
DefaultListModel 
ListSelectionModel DefaultListSelectionModel 
JMenuBar SingleSelectionModel DefaultSingleSelectionModel 
JPopupMenu SingleSelectionModel DefaultSingleSelectionModel 
JProgressBar BoundedRangeModel DefaultBoundedRangeModel 
JScrollBar BoundedRangeModel DefaultBoundedRangeModel 
JSlider BoundedRangeModel DefaultBoundedRangeModel 
JSpinner SpinnerModel AbstractSpinnerModel 
SpinnerDateModel 
SpinnerListModel 
SpinnerNumberModel 
JTabbedPane SingleSelectionModel DefaultSingleSelectionModel 
JTable TableModel AbstractTableModel 
DefaultTableModel 
TableColumnModel DefaultTableColumnModel 
ListSelectionModel DefaultListSelectionModel 
JTextComponent Document AbstractDocument 
PlainDocument 
StyledDocument 
DefaultStyleDocument 


HTMLDocument 
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Table 3-1. Swing Component Models (Continued) 


Component Data Model Interface Implementations 
JToggleButton  ButtonModel  JToggleButton 
ToggleButtonModel 
JTree TreeModel DefaultTreeModel 
TreeSelectionModel DefaultTreeSelectionModel 


JTree.EmptySelectionModel 


When directly accessing the model of a Swing component, if you change the model, all 
registered views are automatically notified. This, in turn, causes the views to revalidate them- 
selves to ensure that the components display their proper current states. This automatic 
propagation of state changes is one reason why MVC has become so popular. In addition, 
using the MVC architecture helps programs become more maintainable as they change over 
time and their complexity grows. No longer will you need to worry about losing state informa- 
tion if you change visual component libraries! 


Summary 


This chapter provided a quick look at how the Swing components use a modified MVC archi- 
tecture. You explored what makes up this modified architecture and how one particular 
component, the JTextArea, maps into this architecture. In addition, the chapter discussed the 
sharing of data models between components and listed all the data models for the different 
Swing components. 

In Chapter 4, you'll start to look at the individual components that make up the Swing 
component library. In addition, you'll explore the Swing component class hierarchy as you 
examine the base JComponent component from the Swing library. 
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CHAPTER 4 


Core Swing Components 


l. Chapter 3, you received a quick introduction to the Model-View-Controller (MVC) pattern 
used by the components of the JFC/Swing project. In this chapter, you”1l begin to explore how 
to use the key parts of the many available components. 

All Swing components start with the JComponent class. Although some parts of the Swing 
libraries aren't rooted with the JComponent class, all the components share JComponent as the 
common parent class at some level of their ancestry. It's with this JComponent class that 
common behavior and properties are defined. In this chapter, you'll look at common function- 
ality such as component painting, customization, tooltips, and sizing. 

As far as specific JComponent descendent classes are concerned, you'll specifically look at 
the JLabel, JButton, and JPanel, three of the more commonly used Swing component classes. 
They require an understanding ofthe Icon interface for displaying images within components, 
as well as ofthe ImagelIcon class for when using predefined images and the GrayFilter class for 
support. In addition, you'll look at the AbstractButton class, which serves as the parent class to 
the JButton. The data model shared by all AbstractButton subclasses is the ButtonModel inter- 
face; you'll explore that and the specific implementation class, the DefaultButtonModel. 


JComponent Class 


The JComponent class serves as the abstract root class from which all Swing components 
descend. The JComponent class has 42 descendent subclasses, each of which inherits much of 
the JComponent functionality. Figure 4-1 shows this hierarchy. 

Although the JComponent class serves as the common root class for all Swing components, 
many classes in the libraries for the Swing project descend from classes other than JComponent. 
Those include all the high-level container objects such as JFrame, JApplet, and JInternalFrame; 
all the MVC-related classes; event-handling—related interfaces and classes; and much more. 
All of these will be discussed in later chapters. 

Although all Swing components extend JComponent, the JComponent class extends the AWT 
Container class, which, in turn, extends from the AWT Component class. This means that many 
aspects ofthe JComponent are shared with both the AWT Component and Container classes. 
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Figure 4-1. JComponent class hierarchy diagram 


Note JComponent extends from the Container class, but most of the JComponent subclasses aren't 
themselves containers of other components. To see if a particular Swing component is truly a container, 
check the BeanInfo for the class to see if the isContainer property is set to true. To get the BeanInfo 
for a class, ask the Introspector. 
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Component Pieces 


The JComponent class defines many aspects of AWT components that go above and beyond the 
capabilities of the original AWT component set. This includes customized painting behavior 
and several different ways to customize display settings, such as colors, fonts, and any other 
client-side settings. 


Painting JComponent Objects 


Because the Swing JComponent class extends from the Container class, the basic AWT painting 
model is followed: All paintingis done through the paint() method, and the repaint() method 
is used to trigger updates. However, many tasks are done differently. The JComponent class opti- 
mizes many aspects of painting for improved performance and extensibility. In addition, the 
RepaintManager class is available to customize painting behavior even further. 


Note The public void update(Graphics g) method, inherited from Component, is never invoked 
on Swing components. 


To improve painting performance and extensibility, the JComponent splits the painting 
operation into three tasks. The public void paint(Graphics g) method is subdivided into three 
separate protected method calls. In the order called, they are paintComponent (g), paintBorder(g), 
and paintChildren(g), with the Graphics argument passed through from the original paint () 
call. The component itselfis first painted through paintComponent (g). Ifyou want to customize 
the painting of a Swing component, you override paintComponent () instead of paint (). Unless 
you want to completely replace all the painting, you would call super. paintComponent() first, 
as shown here, to get the default paintComponent() behavior. 


public class MyComponent extends JPanel ( 
protected void paintComponent (Graphics g) ( 
super .paintComponent (g); 
// Customize after calling super.paintComponent(g) 


J 


Note When running a program that uses Swing components in Java 5.0, the Graphics argument passed 
to the paint () method and on to paintComponent () is technically a Graphics2D argument. Therefore, 
after casting the Graphics argument to a Graphics2D object, you could use the Java 2D capabilities of the 
platform, as you would when defining a drawing Stroke, Shape, or AffineTransform. 
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The paintBorder() and paintChildren() methods tend not to be overridden. The 
paintBorder() method draws a border around the component, a concept described more 
fully in Chapter 7. The paintChildren() method draws the components within the Swing 
container object, if any are present. 

To optimize painting, the JComponent class provides three additional painting properties: 
opaque, optimizedDrawingEnabled, and doubleBuffered. These work as follows: 


+ Opacity: The opaque property for a JComponent defines whether a component is trans- 
parent. When transparent, the container ofthe JComponent must paint the background 
behind the component. To improve performance, you can leave the JComponent opaque 
and let the JComponent draw its own background, instead of relying on the container to 
draw the covered background. 


+ Optimization: The optimizedDrawingEnabled property determines whether immediate 
children can overlap. If children cannot overlap, the repaint time is reduced consider- 
ably. By default, optimized drawing is enabled for most Swing components, except for 
JDesktopPane, JLayeredPane, and JViewport. 


+ Double buffering: By default, all Swing components double buffer their drawing operations 
into a buffer shared by the complete container hierarchy, that is, all the components 
within a window (or subclass). This greatly improves painting performance, because 
when double buffering is enabled (with the doubleBuffered property), there is only a 
single screen update drawn. 


Note For synchronous painting, you can call one ofthe public void paintImmediately() methods. 
(Arguments are either a Rectangle or its parts—position and dimensions.) However, you'll rarely need to 
call this directly unless your program has real-time painting requirements. 


The public void revalidate() method of JComponent also offers painting support. When 
this method is called, the high-level container of the component validates itself. This is unlike 
the AWT approach requiring a direct call to the revalidate() method of that high-level 
component. 

The last aspect of the Swing component painting enhancements is the RepaintManager 
class. 


RepaintManager Class 


The RepaintManager class is responsible for ensuring the efficiency of repaint requests on the 
currently displayed Swing components, making sure the smallest “dirty” region ofthe screen is 
updated when a region becomes invalid. 

Although rarely customized, RepaintManager is public and provides a static installation 
routine to use a custom manager: public static void setCurrentManager(RepaintManager 
manager). To get the current manager, just ask with public static void currentManager 
(JComponent). The argument is usually null, unless you've customized the manager to provide 
component-level support. Once you have the manager, one thing you can do is get the off- 
screen buffer for a component as an Image. Because the buffer is what is eventually shown on 
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the screen, this effectively allows you to do a screen dump of the inside of a window (or any 
JComponent). 


Component comp = ... 

RepaintManager manager = RepaintManager.currentManager (null); 

Image htmlImage = manager .getOffscreenBuffer(comp, comp.getWidth(), 
comp .getHeight()); 

// or 

Image volatileImage = manager.getVolatileOffscreenBuffer(comp, comp.getWidth(), 
comp .getHeight()); 


Table 4-1 shows the two properties of RepaintManager. They allow you to disable double 
buffering for all drawing operations of a component (hierarchy) and to set the maximum 
double buffer size, which defaults to the end user's screen size. 


Table 4-1. RepaintManager Properties 


Property Name Data Type Access 
doubleBufferingEnabled boolean Read-write 
doubleBufferMaximumSize Dimension Read-write 


Tip To globally disable double-buffered drawing, call RepaintManager. currentManager (aComponent). 
setDoubleBufferingEnabled(false). 


Although it's rarely done, providing your own RepaintManager subclass does allow you to 
customize the mechanism of painting dirty regions of the screen, or at least track when the 
painting is finished. Overriding any of the following four methods allows you to customize the 
mechanisms: 


public synchronized void addDirtyRegion(JComponent component, int x, int y, 
int width, int height) 

public Rectangle getDirtyRegion(JComponent component) 

public void markCompletelyClean(JComponent component) 

public void markCompletelyDirty(JComponent component) 


UlDefaults Class 


The UlDefaults class represents a lookup table containing the display settings installed for the 
current look and feel, such as which font to use within a JList, as well as what color or icon 
should be displayed within a JTree node. The use of UIDefaults will be detailed in Chapter 20 
with the coverage of Java's pluggable look and feel architecture. Here, you will get a briefintro- 
duction to the UlDefaults table. 
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Whenever you create a component, the component automatically asks the UlManager to 
look in the UlDefaults table for the current settings for that component. Most color- and font- 
related component settings, as well as some others not related to colors and fonts, are configurable. 
Ifyou don't like a particular setting, you can simply change it by updating the appropriate entry 
in the UlDefaults lookup table. 


Note All predefined resource settings in the UIDefaults table implement the UIResource interface, 
which allows the components to monitor which settings have been customized just by looking for those 
settings that don't implement the interface. 


First, you need to know the name of the UlDefaults setting you want to change. You can 
find the setting names in Appendix A of this book, which contains a complete alphabetical 
listing of all known settings for the predefined look and feel types in J2SE 5.0. (These differ a 
little from release to release.) In addition, included with the description of each component is 
a table containing the UTResource-related property elements. (To find the specific component 
section in the book, consult the table of contents or the index.) 

Once you know the name of a setting, you can store a new setting with the public static 
void put(Object key, Object value) method of UIManager, where key is the key string. For 
instance, the following code will change the default background color of newly created buttons 
to black and the foreground color to red: 


UlManager.put("Button.background", Color.BLACK); 
UlManager.put("Button.foreground", Color.RED); 


Fetching UlResource Properties 


If you're creating your own components, or just need to find out the current value setting, you 
can ask the UlManager. Although the public static Object get(Object key) method is the 
most generic, it requires you to cast the return value to the appropriate class type. Alternatively, you 
could use one of the more specific getXXX() methods, which does the casting for you, to return 
the appropriate type: 


public static boolean getBoolean(Object key) 
public static Border getBorder(Object key) 

public static Color getColor(Object key) 

public static Dimension getDimension(Object key) 
public static Font getFont(Object key) 

public static Icon getIcon(Object key) 

public static Insets getInsets(Object key) 

public static int getInt(Object key) 

public static String getString(Object key) 

public static ComponentUI getUI(JComponent target) 


There is a second set of overloaded methods that accept a second argument for the Locale. 
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Note You can also work with the UlDefaults directly, by calling the public static UlDefaults 
getDefaults() method of UlManager. 


Client Properties 


In addition to the UlManager maintaining a table of key/value pair settings, each instance of 
every component can manage its own set of key/value pairs. This is useful for maintaining 
aspects of a component that may be specific to a particular look and feel, or for maintaining 
data associated with a component without requiring the definition of new classes or methods 
to store such data. 


public final void putClientProperty(Object key, Object value) 
public final Object getClientProperty(Object key) 


Note Calling putClientProperty() with a value of null causes the key to be removed from the client 
property table. 


Forinstance, the JTree class has a property with the Metal look and feel for configuring the 
line style for connecting or displaying nodes within a JTree. Because the setting is specific to 
one look and feel, it doesn't make sense to add something to the tree API. Instead, you set the 
property by calling the following on a particular tree instance: 


tree.putClientProperty("JTree.lineStyle", "None") 


Then, when the look and feel is the default Metal, lines will connect the nodes of the tree. 
If another look and feel is installed, the client property will be ignored. Figure 4-2 shows a tree 
with and without lines. 
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Q red o IN] red F 
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Figure 4-2. A JTree, with and without angled lines 
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Note The list of client properties is probably one of the least documented aspects of Swing. Chapter 20 
lists the available properties | was able to determine. Also, while Metal is the default look and feel, what you 
see is called Ocean. Ocean is a theme of the Metal look and feel and makes Metal look a bit flashier. 


JComponent Properties 


You've seen some of the pieces shared by the different JComponent subclasses. Nowit's time to 
look at the JavaBeans properties. Table 4-2 shows the complete list of properties defined by 
JComponent, including those inherited through the AWT Container and Component classes. 


Table 4-2. Component Properties 


Property Name Data Type Component Container JComponent 
Access Access Access 
accessibleContext AccessibleContext Read-only N/A Read-only 
actionMap ActionMap N/A N/A Read-write 
alignmentX float Read-only Read-only Read-write 
alignmentY float Read-only Read-only Read-write 
ancestorListeners AncestorListener[ ] N/A N/A Read-only 
autoscrolls boolean N/A N/A Read-write 
background Color Read-write N/A Write-only 
bound 
backgroundSet boolean Read-only N/A N/A 
border Border N/A N/A Read-write 
bound 
bounds Rectangle Read-write N/A N/A 
colorModel ColorModel Read-only N/A N/A 
componentCount int N/A Read-only N/A 
componentListeners ComponentListener[ ] Read-only N/A N/A 
componentOrientation ComponentOrientation Read-write N/A N/A 
bound 
componentPopupMenu JPopupMenu N/A N/A Read-write 
components Component[ ] N/A Read-only N/A 
containerListeners ContainerListener[ ] N/A Read-only N/A 
cursor Cursor Read-write N/A N/A 
cursorSet boolean Read-only N/A N/A 
debugGraphicsOptions int N/A N/A Read-write 
displayable boolean Read-only N/A N/A 
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Property Name 


doubleBuffered 
dropTarget 
enabled 


focusable 


focusCycleRoot 


focusCycleRootAncestor 
focusListeners 
focusOwner 


focusTraversalKeysEnabled 


focusTraversalPolicy 


focusTraversalPolicyProvider 


focusTraversalPolicySet 


font 


fontSet 


foreground 


foregroundSet 
graphics 
graphicsConfiguration 
height 
hierarchyBoundsListeners 
hierarchyListeners 
ignoreRepaint 
inheritsPopupMenu 
inputContext 

inputMap 
inputMethodListeners 


inputMethodRequests 


Data Type 


boolean 
DropTarget 


boolean 
boolean 
boolean 


Container 
FocusListener[ ] 
boolean 


boolean 


FocusTraversalPolicy 


boolean 


boolean 


Font 


boolean 


Color 


boolean 

Graphics 
GraphicsConfiguration 
int 
HierarchyBoundsListener[ ] 
HierarchyListener[ ] 
boolean 

boolean 

InputContext 

InputMap 
InputMethodListener[ ] 


InputMethodRequests 
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Component Container JComponent 
Access Access Access 
Read-only N/A Read-write 
Read-write N/A N/A 
Read-write N/A Write-only 

bound 
Read-write N/A N/A 
bound 
N/A Read-write N/A 
bound 
Read-only N/A N/A 
Read-only N/A N/A 
Read-only N/A N/A 
Read-write N/A N/A 
bound 
N/A Read-write N/A 
bound 
N/A Read-write N/A 
bound 
N/A Read-only N/A 
Read-write Write-only Write-only 
bound 
Read-only N/A N/A 
Read-write N/A Write-only 
bound 
Read-only N/A N/A 
Read-only N/A Read-only 
Read-only N/A N/A 
Read-only N/A Read-only 
Read-only N/A N/A 
Read-only N/A N/A 
Read-write N/A N/A 
N/A N/A Read-write 
Read-only N/A N/A 
N/A N/A Read-only 
Read-only N/A N/A 
Read-only N/A N/A 
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Table 4-2. Component Properties (Continued) 


Property Name Data Type Component Container JComponent 
Access Access Access 
inputVerifier  InputVerifier N/A N/A Read-write 
bound 
insets Insets N/A Read-only Read-only 
keyListeners KeyListener[ ] Read-only N/A N/A 
layout LayoutManager N/A Read-write N/A 
lightweight boolean Read-only N/A N/A 
locale Locale Read-write N/A N/A 
bound 
location Point Read-write N/A N/A 
locationOnScreen Point Read-only N/A N/A 
aximumSize Dimension Read-write Read-only Read-write 
bound 
aximumSizeSet boolean Read-only N/A N/A 
inimumSize Dimension Read-write Read-only Read-write 
bound 
inimumSizeSet boolean Read-only N/A N/A 
ouseListeners MouseListener[ ] Read-only N/A N/A 
ouseMotionListeners MouseMotionListener[ ] Read-only N/A N/A 
ousePosition Point Read-only N/A N/A 
ouseWheelListeners MouseWheelListener Read-only N/A N/A 
name String Read-write N/A N/A 
bound 
opaque boolean Read-only N/A Read-write 
bound 
optimizedDrawingEnabled boolean N/A N/A Read-only 
paintingTile boolean N/A N/A Read-only 
parent Container Read-only N/A N/A 
preferredSize Dimension Read-write Read-only Read-write 
bound 
preferredSizeSet boolean Read-only N/A N/A 
propertyChangeListeners PropertyChangelistener[ ] Read-only N/A N/A 
registeredKeyStrokes KeyStroke[ ] N/A N/A Read-only 
requestFocusEnabled boolean N/A N/A Read-write 


rootPane JRootPane N/A N/A Read-only 
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Table 4-2. Component Properties (Continued) 
Property Name Data Type Component Container JComponent 
Access Access Access 

showing boolean Read-only N/A N/A 
size Dimension Read-write N/A N/A 
toolkit Toolkit Read-only N/A N/A 
tooltipText String N/A N/A Read-write 
topLevelAncestor Container N/A N/A Read-only 
transferHandler TransferHandler N/A N/A Read-write 

bound 
treeLock Object Read-only N/A N/A 
uiClassID String N/A N/A Read-only 
valid boolean Read-only N/A N/A 
validateRoot boolean N/A N/A Read-only 
verifyInputWhenFocusTarget boolean N/A N/A Read-write 

bound 
vetoableChangeListeners VetoableChangeListener[] N/A N/A Read-only 
visible boolean Read-write N/A Write-only 
visibleRect Rectangle N/A N/A Read-only 
width int Read-only N/A Read-only 
Xx int Read-only N/A Read-only 
y int Read-only N/A Read-only 


Note Additionally, there's a read-only class property defined at the Object level, the parent of the 


Component class. 


Including the properties from the parent hierarchy, approximately 92 properties of 
JComponent exist. As that number indicates, the JComponent class is extremely well suited for 
visual development. There are roughly ten categories of JComponent properties, as described in 
the following sections. 


Position-Oriented Properties 


The x and y properties define the location of the component relative to its parent. The 
locationOnScreen is just another location for the component, this time relative to the screen's 
origin (the upper-left corner). The width and height properties define the size ofthe component. 
The visibleRect property describes the part ofthe component visible withinthe topLevelAncestor, 
whereas the bounds property defines the component's area, whether visible or not. 


78 


CHAPTER 4 CORE SWING COMPONENTS 


Component-Set-Oriented Properties 


The components and componentCount properties enable you to find out what the children 
components are of the particular JComponent. For each component in the components property 
array, the current component would be its parent. In addition to determining a component's 
parent, you can find out its rootPane or topLevelAncestor. 


Focus-Oriented Properties 


The focusable, focusCycleRoot, focusCycleRootAncestor, focusOuner, focusTraversalKeysEnabled, 
focusTraversalPolicy, focusTraversalPolicyProvider, focusTraversablePolicySet, 
requestFocusEnabled, verifyInputWhenFocusTarget, and inputVerifier properties define the 
setoffocus-oriented properties. These properties control the focus behavior of JComponent and 
were discussed in Chapter 2. 


Layout-Oriented Properties 


The alignmentX, alignmentY, componentOrientation, layout, maximumSize, minimumSize, 
preferredSize, maximumSizeSet, minimumSizeSet, and preferredSizeSet properties are 
used to help with layout management. 


Painting Support Properties 


The background and foreground properties describe the current drawing colors. The font property 
describes the text style to draw. The backgroundSet, foregroundSet, and fontSet properties 
describe ifthe properties are explicitly set. The insets and border properties are intermixed 
to describe the drawing of a border around a component. The graphics property permits real- 
time drawing, although the paintImmediately() method might now suffice. 

To improve performance, there are the opaque (false is transparent), doubleBuffered, 
ignoreRepaint, and optimizedDrawingEnabled properties. The colorModel and paintingTile 
properties store intermediate drawing information. The graphicsConfiguration property adds 
support for virtual devices. 

debugGraphicsOption allows you to slow down the drawing of your component ifyou can't 
figure out why it's not painted properly. The debugGraphicsOption property is set to one or 
more of the settings shown in Table 4-3. 


Table 4-3. DebugGraphics Settings 


DebugGraphics Settings Description 


DebugGraphics .BUFFERED_OPTION Causes a window to pop up, displaying the drawing of 
the double-buffered image 


DebugGraphics.FLASH_OPTION Causes the drawing to be done more slowly, flashing 
between steps 


DebugGraphics.LOG_OPTION Causes a message to be printed to the screen as each 
step is done 


DebugGraphics.NONE_OPTION Disables all options 
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You can combine multiple DebugGraphics settings with the bitwise OR (|) operator, as in 
this example: 


JComponent component = new ...(); 
component .setDebugGraphicsOptions(DebugGraphics.BUFFERED_OPTION | 
DebugGraphics.FLASH_OPTION | DebugGraphics.LOG_OPTION); 


Internationalization Support Properties 


The inputContext, inputMethodRequests, and locale properties help when creating multilingual 
operations. 


State Support Properties 


To get state information about a component, all you have to do is ask; there's much you can 
discover. The autoscroll1s property lets you place a component within a JVienport and it auto- 
matically scrolls when dragged. The validateRoot property is used when revalidate() has 
been called and returns true when the current component is at the point it should stop. The 
remaining seven properties are self-explanatory: displayable, dropTarget, enabled, lightweight, 
showing, valid, and visible. 


Event Support Properties 


The registeredKeyStrokes, inputMap, and actionMap properties allow you to register keystroke 
responses with a window. All the getXXXListeners() methods allow you to get the current set 
of listeners for a particular listener type. 


Pop-Up Support Properties 


There are two types of pop-ups associated with a component: tooltips and pop-up menus. 
The too1TipText property is set to display pop-up support text over a component. The 
componentPopupMenu and inheritsPopupMenu properties are related to automatically showing 
pop-up menus associated with the component. The mousePosition property helps to position 
these. 


Other Properties 


The remaining properties don't seem to have any kind of logical grouping. The accessibleContext 
property is for support with the javax.accessibility package. The cursor property lets you 
change the cursor to one of the available cursors, where cursorSet is used to recognize when 
the property is explicitly set. The toolkit property encapsulates platform-specific behaviors 
for accessing system resources. The transferHandler property is there for drag-and-drop 
support. The name property gives you the means to recognize a particular instance of a class. 
The treelock propertyis the component tree-synchronization locking resource. The uiClassID 
property is new, it allows subclasses to return the appropriate class ID for their specific instance. 
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Handling JComponent Events 


There are many different types of events that all JComponent subclasses share. Most of these 
come from parent classes, like Component and Container. First, you'll explore the use of 
PropertyChangeListener, which is inherited from Container. Then you'1l look at the use oftwo 
event-handling capabilities shared by all JComponent subclasses: VetoableChangeListener and 
AncestorListener. Finally, you'll see the complete set of listeners inherited from Component. 


Listening to Component Events with a PropertyChangeListener 


The JComponent class has several component bound properties, directly and indirectly. By 
binding a PropertyChangeListener to the component, you can listen for particular JComponent 
property changes, and then respond accordingly. 


public interface PropertyChangeListener extends EventListener ( 
public void propertyChange(PropertyChangeEvent propertyChangeEvent); 
, 


To demonstrate, the PropertyChangeListener in Listing 4-1 demonstrates the behavior you 
might need when listening for changes to an Action type property within a JButton component. 
The property that changes determines which if block is executed. 


Listing 4-1. Watching for Changes to a JButton 


import java.beans.*; 
import javax.swing.*; 


public class ActionChangedListener implements PropertyChangelistener ( 
private JButton button; 


public ActionChangedListener(JButton button) ( 
this.button = button; 


J 


public void propertyChange(PropertyChangeEvent e) ( 

String propertyName = e.getPropertyName(); 

if (e.getPropertyName().equals(Action.NAME)) € 
String text = (String)e.getNenValue(); 
button.setText(text); 
button.repaint(); 

) else if (propertyName.equals("enabled")) £ 
Boolean enabledState = (Boolean)e.getNewValue(); 
button.setEnabled(enabledState.booleanValue()); 
button.repaint(); 
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j else if (e.getPropertyName().equals(Action.SMALL_ICON)) £ 
Icon icon = (Icon)e.getNewValue(); 
button.setIcon(icon); 
button.invalidate(); 
button.repaint(); 


Note You can bind a PropertyChangeListener to a specific property by adding the listener with 
addPropertyChangeListener(String propertyName, PropertyChangeListener listener). 
This allows your listener to avoid having to check for the specific property that changed. 


Listening to JComponent Events with a VetoableChangeListener 


The VetoableChangelListener is another JavaBeans listener that Swing components use. 
It works with constrained properties, whereas the PropertyChangeListener works with 
only bound properties. A key difference between the two is that the public void 
vetoableChange(PropertyChangeEvent propertyChangeEvent) method can throw a 
PropertyVetoException if the listener doesn't like the requested change. 


public interface VetoableChangeListener extends EventListener ( 
public void vetoableChange(PropertyChangeEvent propertyChangeEvent) 
throws PropertyVetoException; 


Note Only one Swing class, JInternalFrame, has constrained properties. The listener is meant primarily for 
programmers to use with their own newly created components. 


Listening to JComponent Events with an AncestorListener 


You can use an AncestorListener to find out when a component moves, is made visible, or is 
made invisible. It's useful if you permit your users to customize their screens by moving 
components around and possibly removing components from the screens. 


public interface AncestorlListener extends EventListener ( 
public void ancestorAdded(AncestorEvent ancestorEvent); 
public void ancestorMoved(AncestorEvent ancestorEvent); 
public void ancestorRemoved(AncestorEvent ancestorEvent); 


) 
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To demonstrate, Listing 4-2 associates an AncestorListener with the root pane ofa JFrame. 
You'll see the messages Removed, Added, and Moved when the program first starts up. In addition, 
you'll see Moved messages when you drag the frame around. 


Listing 4-2. Listening for Ancestor Events 


import java.awt.*; 
import javax.swing.*; 
import javax.swing.event.*; 


public class AncestorSampler ( 
public static void main (String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("Ancestor Sampler"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


AncestorListener ancestorListener = new AncestorListener() ( 
public void ancestorAdded(AncestorEvent ancestorEvent) ( 
System.out.println ("Added"); 
) 
public void ancestorMoved(AncestorEvent ancestorEvent) ( 
System.out.println ("Moved"); 


J 


public void ancestorRemoved(AncestorEvent ancestorEvent) ( 
System.out.println ("Removed"); 

) 
5 
frame.getRootPane().addAncestorListener(ancestorListener); 
frame.setSize(300, 200); 
frame.setVisible(true); 
frame.getRootPane().setVisible(false); 
frame.getRootPane().setVisible(true); 


Í 
5 
EventQueue.invokeLater(runner); 
y 
) 


Listening to Inherited Events of a JComponent 


In addition to the ability to listen for an instance of an AncestorEvent or PropertyChangeEvent 
with a JComponent, the JComponent inherits the ability to listen to many other events from its 
Container and Component superclasses. 
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Table 4-4 lists ten event listeners. You may find yourself using the JComponent listener 
interfaces quite a bit, but the older ones work, too. Use the ones most appropriate for the task 
at hand. 


Table 4-4. Component Inherited Event Listeners 

Class Event Listener Event Object 

Component ComponentListener componentHidden(ComponentEvent) 
componentMoved(ComponentEvent) 
componentResized(ComponentEvent) 
componentShown(ComponentEvent) 

Component FocusListener focusGained(FocusEvent) 
focusLost(FocusEvent) 

Component HierarchyBoundsListener ancestorMoved(HierarchyEvent) 


ancestorResized(HierarchyEvent) 


Component HierarchyListener hierarchyChanged(HierarchyEvent) 
Component InputMethodListener caretPositionChanged 
(InputMethodEvent) 


inputMethodTextChanged 
(InputMethodEvent) 

Component KeyListener keyPressed(KeyEvent) 

keyReleased(KeyEvent) 

keyTyped(KeyEvent) 
Component MouseListener ouseClicked(MouseEvent) 
ouseEntered(MouseEvent) 
ouseExited(MouseEvent) 
ousePressed(MouseEvent) 


ouseReleased(MouseEvent) 


Component MouseMotionListener ouseDragged(MouseEvent) 


ouseMoved(MouseEvent) 


Component MouseWheelListener ouseWheelMoved(MouselheelEvent) 
Container ContainerListener componentAdded(ContainerEvent) 


componentRemoved(ContainerEvent) 
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JToolTip Class 


The Swing components support the ability to display brief pop-up messages when the cursor 
rests over them. The class used to display pop-up messages is JToo1Tip. 


Creating a JToolTip 


Calling the public void setTool1TipText(String text) method of JComponent automatically 
causes the creation of a JToo1Tip instance when the mouse rests over a component with the 
installed pop-up message. You don't normally call the JToo1Tip constructor directly. There's 
only one constructor, and it's of the no-argument variety. 

Tooltip textis normally one line long. However, if the text string begins with <html> (in any 
case), then the contents can be any HTML 3.2 formatted text. For instance, the following line 
causes the pop-up message shown in Figure 4-3: 


component .setToo1TipText("<html>Too1tip<br>Message"); 


Pot same A 


ooltip 
Message 


Figure 4-3. HTML-based tooltip text 


Creating Customized JToolTip Objects 


You can easily customize the display characteristics for all pop-up messages by setting UIResource 
elements for JToo1Tip, as shown in the “Customizing a JToolTip Look and Feel” section later in 
this chapter. 

The JComponent class defines an easy way for you to customize the display characteristics 
of the tooltip when it's placed over a specific component. Simply subclass the component you 
want to customize and override its inherited public JToo1Tip createToo1Tip() method. The 
createToo1Tip() method is called when the Too1TipManager has determined that it's time to 
display the pop-up message. 

To customize the pop-up tooltip appearance, just override the method and customize the 
JToo1Tip returned from the inherited method. For instance, the following source demonstrates 
the setting of a custom coloration for the tooltip for a JButton, as shown in Figure 4-4. 


JButton b = new JButton("Hello, World") £ 
public JToo1Tip createToolTip() ( 
JToo1Tip tip = super.createToo1Tip(); 
tip.setBackground(Color.YELLOW); 
tip.setForeground(Color.RED); 
return tip; 
y 
5 
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Hello, World 


Hello, World 


Figure 4-4. Tooltip text displayed with custom colors 


Afterthe JToo1Tip has been created, you can configure the inherited JComponent properties 
or any of the properties specific to JToo1Tip, as shown in Table 4-5. 


Table 4-5. JToolTip Properties 


Property Name Data Type Access 

accessibleContext AccessibleContext Read-only 
component JComponent Read-write 
tipText String Read-write 
UI Too1Tipul Read-only 
UlClassID String Read-only 


Displaying Positional Tooltip Text 


Swing components can even support the display of different tooltip text, depending on where 
the mouse pointer is located. This requires overriding the public boolean contains(int x, int y) 
method, which originates from the Component class. 

For instance, after enhancing the customized JButton created in the previous section 
(Figure 4-4), the tooltip text will differ, depending on whether or not the mouse pointer is 
within 50 pixels from the left edge of the component. 


JButton button = new JButton("Hello, World") £ 
public JToo1Tip createTool1Tip() ( 
JToo1Tip tip = super.createToo1Tip(); 
tip.setBackground(Color.YELLOW) ; 
tip.setForeground(Color.RED); 
return tip; 
) 
public boolean contains(int x, int y) f 
if (x < 50) ( 
setToo1TipText("Got Green Eggs?"); 
) else f 
setToo1TipText("Got Ham?"); 
) 
return super.contains(x, y); 
) 
E 
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Customizing a JToolTip Look and Feel 


Each installable Swing look and feel provides a different JToo1Tip appearance and a set of 
default UTResource value settings. Figure 4-5 shows the appearance ofthe JToo1Tip component 
for the preinstalled set of look and feel types: Motif, Windows, and Ocean. 


E oa lora] PS l0x 


| Ñ Hello, World , pi , Hello, World 
Got Green Eggs? 


Got Green Eggs?| 


Got Green Egas? 


Motif Windows Ocean 


Figure 4-5. JToolTip under different look and feel types 


The available set ofUTResource-related properties for a JToo1Tip is shown in Table 4-6. 
For the JToo1Tip component, there are nine different properties. 


Table 4-6. JToo!Tip UlResource Elements 


Property String Object Type 
ToolTip.backgroundInactive Color 
Too1Tip.border Border 
Tool1Tip.borderInactive Color 
Tool1Tip.font Font 
Tool1Tip.foreground Color 
Tool1Tip.foregroundInactive Color 
ToolTip.hideAccelerator Boolean 
Too1Tipul String 


As noted earlier in this chapter, the JToo1Tip class supports the display of arbitrary HTML 
content. This permits the display of multiple-column and multiple-row input. 


ToolTipManager Class 


Although the JToo1Tip is something ofa passive object, in the sense that the JComponent creates 
and shows the JToo1Tip on its own, there are many more configurable aspects ofits usage. 
However, these configurable aspects are the responsibility of the class that manages tooltips, 
not the JToo1Tip itself. The class that manages tooltip usage is aptly named ToolTipManager. 
With the Singleton design pattern, no constructor for Too1TipManager exists. Instead, you have 
access to the current manager through the static sharedInstance() method of ToolTipManager. 
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ToolTipManager Properties 


Once you have accessed the shared instance of Too1TipManager, you can customize when and 
if tooltip text appears. As Table 4-7 shows, there are five configurable properties. 


Table 4-7. Too!TipManager Properties 


Property Name Data Type Access 

dismissDelay int Read-write 
enabled boolean Read-write 
initialDelay int Read-write 
lightWeightPopupEnabled boolean Read-write 
reshowDelay int Read-only 


Initially, tooltips are enabled, but you can disable them with ToolTipManager. 
sharedInstance().setEnabled(false). This allows you to always associate tooltips with 
components, while letting the end user enable and disable them when desired. 

There are three timing-oriented properties: initialDelay, dismissDelay, and reshowDelay. 
They all measure time in milliseconds. The initialDelay property is the number of milliseconds 
the user must rest the mouse inside the component before the appropriate tooltip text appears. 
The dismissDelay specifies the length of time the text appears while the mouse remains 
motionless; ifthe user moves the mouse, it also causes the text to disappear. The reshonDelay 
determines how long a user must remain outside a component before reentry would cause the 
pop-up text to reappear. 

The lightWeightPopupEnabled property is used to determine the pop-up window type to 
hold the tooltip text. Ifthe property is true and the pop-up text fits entirely within the bounds 
of the top-level window, the text appears within a Swing JPanel. Ifthis property is false and the 
pop-up text fits entirely within the bounds of the top-level window, the text appears within an 
AWT Panel. If part of the text wouldn't appear within the top-level window no matter what the 
property settingis, the pop-up text would appear within a Window. 

Although not properties of Too1TipManager, two other methods of Too1TipManager are 
worth mentioning: 


public void registerComponent(JComponent component) 
public void unregisterComponent(JComponent component) 


When you call the setToo1TipText() method of JComponent, this causes the component to 
register itself with the Too1TipManager. There are times, however, when you need to register 
a component directly. This is necessary when the display of part of a component is left to 
another renderer. With JTree, for instance, a TreeCellRenderer displays each node of the tree. 
When the renderer displays the tooltip text, you “register” the JTree and tell the renderer what 
text to display. 
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JTree tree = new JTree(...); 
Too1TipManager.sharedInstance().registerComponent (tree); 
TreeCellRenderer renderer = new ATreeCellRenderer(...); 
tree.setCellRenderer(renderer); 


public class ATreeCellRenderer implements TreeCellRenderer ( 


public Component getTreeCellRendererComponent(JTree tree, Object value, 
boolean selected, boolean expanded, boolean leaf, int row, boolean hasFocus) ( 


renderer.setToolTipText("Some Tip”); 
return renderer; 
J 
y 


Note If this sounds confusing, don't worry. We'll revisit the JTree in Chapter 17. 


JLabel Glass 


The first real Swing component to examine closely is the simplest, the JLabel. The JLabel 
serves as the replacement component for the AWT Label but it can do much more. Whereas the 
AWT Label is limited to a single line of text, the Swing JLabel can have text, images, or both. The 
text can be a single line of text or HTML. In addition JLabel can support different enabled and 
disabled images. Figure 4-6 shows some sample JLabel components. 


Pese A 


Text Label AN 
HTML 
AN Warning Label 
Multi-line 


Figure 4-6. Sample JLabel components 


Note A JLabel subclass is used as the default renderer for each of the JList, JComboBox, JTable, 
and JTree components. 
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Creating a JLabel 


There are six constructors for JLabel: 


public JLabel() 
JLabel label = new JLabel(); 


public JLabel(Icon image) 
Icon icon = new Imagelcon("dog.jpg"); 
JLabel label = new JLabel (icon); 


public JLabel(Icon image, int horizontalAlignment) 
Icon icon = new Imagelcon("dog.jpg"); 


JLabel label = new JLabel(icon, JLabel.RIGHT); 


public JLabel(String text) 
JLabel label = new JLabel("Dog"); 


public JLabel(String text, int horizontalAlignment) 
JLabel label = new JLabel("Dog", JLabel.RIGHT); 


public JLabel(String text, Icon icon, int horizontalAlignment) 
Icon icon = new Imagelcon("dog.jpg"); 
Jlabel label = new JLabel("Dog", icon, JLabel.RIGHT); 


With the constructors for JLabel, you can customize any of three properties of the 
JLabel: text, icon, or horizontalAlignment. By default, the text and icon properties are empty, 
whereas the initial horizontalAlignment property setting depends on the constructor arguments. 
These settings can be any of JLabel.LEFT, JLabel.CENTER, or JLabel .RIGHT. In most cases, not 
specifying the horizontalAlignment setting results in a left-aligned label. However, if only the 
initial icon is specified, then the default alignment is centered. 


JLabel Properties 


Table 4-8 shows the 14 properties of JLabel. They allow you to customize the content, position, 
and (in a limited sense) the behavior of the JLabel. 


Table 4-8. JLabel Properties 


Property Name Data Type Access 
accessibleContext AccessibleContext Read-only 
disabledIcon Icon Read-write bound 
displayedMnemonic char Read-write bound 
displayedMnemonicIndex int Read-write bound 
horizontalAlignment int Read-write bound 


horizontalTextPosition int Read-write bound 
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Table 4-8. JLabel Properties (Continued) 


Property Name Data Type Access 

icon Icon Read-write bound 
iconTextGap int Read-write bound 
labelFor Component Read-write bound 
text String Read-write bound 
UI LabelUI Read-write 
UlClassID String Read-only 
verticalAlignment int Read-write bound 
verticalTextPosition int Read-write bound 


The content ofthe JLabel is the text and its associated image. Displaying an image within 
a JLabel will be discussed in the “Interface Icon” section later in this chapter. However, you can 
display different icons, depending on whether the JLabel is enabled or disabled. By default, the 
icon is a grayscaled version ofthe enabled icon, ifthe enabled icon comes from an Image object 
(ImagelIcon, as described later in the chapter). Ifthe enabled icon doesn't come from an Image, 
there's no icon when JLabel is disabled, unless manually specified. 

The position of the contents of the JLabel is described by four different properties: 
horizontalAlignment, horizontalTextPosition, verticalAlignment, and verticalTextPosition. 
The horizontalAlignment and verticalAlignment properties describe the position ofthe contents 
ofthe JLabel within the container in which it's placed. 


Note Alignments have an effect only if there's extra space for the layout manager to position the compo- 
nent. If you're using a layout manager such as FlowLayout, which sizes components to their preferred size, 
these settings will effectively be ignored. 


The horizontal position can be any of the JLabel constants LEFT, RIGHT, or CENTER. The 
vertical position can be TOP, BOTTOM, or CENTER. Figure 4-7 shows various alignment settings, 
with the label reflecting the alignments. 

The text position properties reflect where the text is positioned relative to the icon when 
both are present. The properties can be set to the same constants as the alignment constants. 
Figure 4-8 shows various text position settings, with each label reflecting the setting. 


Note The constants for the different positions come from the SwingConstants interface that the 
JLabel class implements. 
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Figure 4-7. Various JLabel alignments 
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Figure 4-8. Various JLabel text positions 


JLabel Event Handling 


No event-handling capabilities are specific to the JLabel. Besides the event-handling capabilities 
inherited through JComponent, the closest thing there is for event handling with the JLabel is the 
combined usage of the displayedMnemonic, displayedMnemonicIndex, and labelFor properties. 
When the displayedMnemonic and labelFor properties are set, pressing the keystroke specified 
by the mnemonic, along with the platform-specific hotkey (usually Alt), causes the input focus 
to shift to the component associated with the labelFor property. This can be helpful when a 
component doesn't have its own manner of displaying a mnemonic setting, such as with all the 
text input components. Here is an example, which results in the display shown in Figure 4-9: 


JLabel label = new JLabel ("Username"); 
JTextField textField = new JTextField(); 
label.setDisplayedMnemonic(KeyEvent.VK_U); 
label.setlLabelFor(textField); 


AE 


Usernamel 


Figure 4-9. Using a JLabel to display the mnemonic for another component 
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The displayedMnemonicIndex property adds the ability for the mnemonic highlighted to 
not be the first instance of mnemonic in the label's text. The index you specify represents the 
position in the text, not the instance of the mnemonic. To highlight the second ein Username, 
you would specify an index of 7: label. setDisplayedMnemonicIndex(7). 


Note The component setting of the 1abelFor property is stored as a client property of the JLabel with 
the LABELED_BY_PROPERTY key constant. The setting is used for accessibility purposes. 


Customizing a JLabel Look and Feel 


Each installable Swing look and feel provides a different JLabel appearance and set of default 
UTResource value settings. Although appearances differ based on the current look and feel, the 
differences are minimal within the preinstalled set of look and feel types. Table 4-9 shows the 
available set of UIResource-related properties for a JLabel. There are eight different properties 
for the JLabel component. 


Table 4-9. JLabel UlResource Elements 


Property String Object Type 
Label .actionMap ActionMap 
Label.background Color 
Label.border Border 
Label.disabledForeground Color 
Label.disabledShadow Color 
Label. font Font 

Label. foreground Color 
LabelUI String 


Interface Icon 


The Icon interface is used to associate glyphs with various components. A glyph (like a symbol 
on a highway sign that conveys information nonverbally, such as “winding road ahead!”) can 
be a simple drawing or a GIF image loaded from disk with the ImageIcon class. The interface 
contains two properties describing the size and a method to paint the glyph. 


public interface Icon ( 
// Properties 
public int getIconHeight(); 
public int getIconWidth(); 
// Other methods 
public void paintIcon(Component c, Graphics g, int x, int y); 
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Creating an Icon 


Creating an Icon is as simple as implementing the interface. All you need to do is specify the 
size ofthe icon and what to draw. Listing 4-3 shows one such Icon implementation. The iconis 
a diamond-shaped glyph in which the size, color, and filled-status are all configurable. 


Tip In implementing the paintIcon() method of the Icon interface, translate the drawing coordinates 
of the graphics context based on the x and y position passed in, and then translate them back when the 
drawing is done. This greatly simplifies the different drawing operations. 


Listing 4-3. Reusable Diamond Icon Definition 


import javax.swing.*; 
import java.awt.*; 
public class DiamondIcon implements Icon ( 
private Color color; 
private boolean selected; 
private int width; 
private int height; 
private Polygon poly; 
private static final int DEFAULT_WIDTH = 10; 
private static final int DEFAULT_HEIGHT = 10; 


public DiamondIcon(Color color) f 
this(color, true, DEFAULT WIDTH, DEFAULT_HEIGHT); 
l 


public DiamondIcon(Color color, boolean selected) ( 
this(color, selected, DEFAULT WIDTH, DEFAULT HEIGHT); 
h 


public DiamondIcon(Color color, boolean selected, int width, int height) £ 
this.color = color; 
this.selected = selected; 
this.width = width; 
this.height = height; 
initPolygon(); 
) 


private void initPolygon() ( 
poly = new Polygon(); 
int halfWidth = width/2; 
int halfHeight = height/2; 
poly.addPoint(O, halfHeight); 
poly.addPoint(halfWidth, 0); 
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poly.addPoint(width, halfHeight); 
poly.addPoint(halfWidth, height); 


J 


public int getIconHeight() ( 
return height; 


) 


public int getIconWidth() ( 
return width; 


J 


public void paintIcon(Component c, Graphics g, int x, int y) [ 
g.setColor(color); 
g-translate(x, y); 
if (selected) ( 
g-fillPolygon(poly); 


+ else £ 
g.drawPolygon(poly); 
) 
g.translate(-x, -y); 
) 
) 
Using an Icon 


Once you have your Icon implementation, using the Icon is as simple as finding a component 
with an appropriate property. For example, here's the icon with a JLabel: 


Icon icon = new DiamondIcon(Color.RED, true, 25, 25); 
JLabel label = new JLabel (icon); 


Figure 4-10 shows what such a label might look like. 


12 taveticon AE 


Figure 4-10. Using an Icon in a JLabel 


Imagelcon Class 


The ImagelIcon class presents an implementation of the Icon interface for creating glyphs from 
AWT Image objects, whether from memory (a byte[ ]), off a disk (a file name), or over the 

network (a URL). Unlike with regular Image objects, the loading of an ImagelIcon is immediately 
started when the ImagelIcon is created, though it might not be fully loaded when used. In addition, 
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unlike Image objects, ImageIcon objects are serializable so that they can be easily used by 
JavaBean components. 


Creating an Imagelcon 
There are nine constructors for an Imagelcon: 
public Imagelcon() 


Icon icon = new Imagelcon(); 
icon.setImage(anImage); 


public Imagelcon(Image image) 
Icon icon = new Imagelcon(anImage); 


public Imagelcon(String filename) 
Icon icon = new Imagelcon(filename); 


public Imagelcon(URL location) 
Icon icon = new Imagelcon(url); 


public Imagelcon(byte imageData[]) 
Icon icon = new Imagelcon(aByteArray); 


public Imagelcon(Image image, String description) 
Icon icon = new Imagelcon(anImage, "Duke"); 


public Imagelcon(String filename, String description) 
Icon icon = new Imagelcon(filename, filename); 


public Imagelcon(URL location, String description) 
Icon icon = new Imagelcon(url, location.getFile()); 


public Imagelcon(byte imageData[], String description) 
Icon icon = new Imagelcon(aByteArray, "Duke"); 


The no-argument version creates an uninitialized version (empty). The remaining eight 
offer the ability to create an ImageIcon from an Image, byte array, file name String, or URL, with 
or without a description. 


Using an Imagelcon 


Using an ImageIcon is as simple as using an Icon: just create the ImageIcon and associate it with 
a component. 


Icon icon = new Imagelcon("Warn.gif"); 
JLabel label3 = new JLabel("Warning", icon, JLabel.CENTER) 
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Imagelcon Properties 


Table 4-10 shows the six properties of ImageIcon. The height and width ofthe ImageIcon are the 
height and width of the actual Image object. The imageLoadStatus property represents the results of 
the loading of the ImageIcon from the hidden MediaTracker, either MediaTracker.ABORTED, 
MediaTracker.ERRORED, or MediaTracker. COMPLETE. 


Table 4-10. Imagelcon Properties 


Property Name Data Type Access 

description String Read-write 
iconHeight int Read-only 
iconWidth int Read-only 
image Image Read-write 
imageLoadStatus int Read-only 
image0bserver Image0bserver Read-write 


Sometimes, it's useful to use an ImageIcon to load an Image, and then just ask for the Image 
object from the Icon. 


Imagelcon imagelcon = new Imagelcon(...); 
Image image = imagelcon.getImage(); 


There is one major problem with using ImageIcon objects: They don't work when the 
image and class file using theicon are both loaded in aJAR (Java archive) file, unless you explicitly 
specify the full URL for the file within the JAR (jar:http://www.example.com/directory/ 
foo.jar!/com/example/image.gif). You can't just specify the file name as a String and let the 
ImageIcon find the file. You must manually get the image data first, and then pass the data 
along to the Imagelcon constructor. 

To help with loading images outside JAR files, Listing 4-4 shows an ImageLoader class that 
provides a public static Image getImage(Class relativeClass, String filename) method. 
You specify both the base class where the image file relative is found and the file name for the 
image file. Then you just need to pass the Image object returned to the constructor of Imagelcon. 


Listing 4-4. Image Loading Support Class 


import java.awt.*; 
import java.io.*; 


public final class ImageLoader ( 


private ImageLoader() ( 


) 
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public static Image getImage(Class relativeClass, String filename) ( 
Image returnValue = null; 
InputStream is = relativeClass.getResourceAsStream(filename); 
if (is != null) € 
BufferedInputStream bis = new BufferedInputStream(is); 
ByteArray0utputStream baos = new ByteArray0utputStream(); 
try ( 
int ch; 
while ((ch = bis.read()) != -1) 4 
baos .write(ch); 
) 
returnValue = Toolkit.getDefaultTool1kit().createImage(baos.toByteArray()); 
) catch (IOException exception) ( 
System.err.println("Error loading: 
) 
y 
return returnValue; 


J 


" 


+ filename); 


J 
Here's how you use the helper class: 


Image warnImage = Imageloader.getImage(LabelJarSample.class, "Warn.gif"); 
Icon warnIcon = new Imagelcon(warnImage); 
JLabel label2 = new JLabel (warnIcon); 


Tip Keep in mind that the Java platform supports GIF89A animated images. 


GrayFilter Class 


One additional class worth mentioning here is GrayFilter. Many of the Swing component 
classes rely on this class to create a disabled version of an Image to be used as an Icon. The 
components use the class automatically, but there might be times when you need an AWT 
ImageFilter that does grayscales. You can convert an Image from normal to grayed out with 
a call to the one useful method of the class: public static Image createDisabledImage 
(Image image). 


Image normalImage = ... 
Image grayImage = GrayFilter.createDisabledImage(normalImage) 


You can now use the grayed-out image as the Icon on a component: 


Icon warninglcon = new Imagelcon(grayImage); 
JLabel warninglabel = new JLabel(warninglcon); 
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AbstractButton Class 


The AbstractButton class is an important Swing class that works behind the scenes as the 
parent class of all the Swing button components, as shown at the top of Figure 4-1. The 
JButton, described in the “Button Class” section later in this chapter, is the simplest of the 
subclasses. The remaining subclasses are described in later chapters. 

Each of the AbstractButton subclasses uses the ButtonModel interface to store their 
data model. The DefaultButtonModel class is the default implementation used. In addition, 
you can group any set of AbstractButton objects into a ButtonGroup. Although this grouping 
is most natural with the JRadioButton and JRadioButtonMenultem components, any of the 
AbstractButton subclasses will work. 


AbstractButton Properties 


Table 4-11 lists the 32 properties (with mnemonic listed twice) of AbstractButton shared by all its 
subclasses. They allow you to customize the appearance of all the buttons. 


Table 4-11. AbstractButton Properties 


Property Name Data Type Access 

action Action Read-write bound 
actionCommand String Read-write 
actionListeners ActionListener[ ] Read-only 
borderPainted boolean Read-write bound 
changeListeners ChangeListener[ ] Read-only 
contentAreaFilled boolean Read-write bound 
disabledIcon Icon Read-write bound 
disabledSelectedIcon Icon Read-write bound 
displayedMnemonicIndex int Read-write bound 
enabled boolean Write-only 
focusPainted boolean Read-write bound 
horizontalAlignment int Read-write bound 
horizontalTextPosition int Read-write bound 
icon Icon Read-write bound 
iconTextGap int Read-write bound 
itemListeners ItemListener[ ] Read-only 

layout LayoutManager Write-only 

margin Insets Read-write bound 


mnemonic char Read-write bound 
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Table 4-11. AbstractButton Properties (Continued) 


Property Name Data Type Access 

mnemonic int Write-only 

model ButtonModel Read-write bound 
multiClickThreshhold long Read-write 
pressedIcon Icon Read-write bound 
rolloverEnabled boolean Read-write bound 
rolloverIcon Icon Read-write bound 
rolloverSelectedIcon Icon Read-write bound 
selected boolean Read-write 
selectedIcon Icon Read-write bound 
selectedObjects Object[ ] Read-only 

text String Read-write bound 
UI ButtonUI Read-write 
verticalAlignment int Read-write bound 
verticalTextPosition int Read-write bound 


Note AbstractButton has a deprecated label property. You should use the equivalent text 
property instead. 


One property worth mentioningis multiClickThreshhold. This property represents a time, 
in milliseconds. If a button is selected with a mouse multiple times within this time period, 
additional action events won't be generated. By default, the value is zero, meaning each press 
generates an event. To avoid accidental duplicate submissions from happening in important 
dialogs, set this value to some reasonable level above zero. 


Tip Keep in mind that all AbstractButton children can use HTML with its text property to display 
HTML content within the label. Just prefix the property setting with the string <html>. 


ButtonModel/Class DefaultButtonModel Interface 


The ButtonModel interface is used to describe the current state ofthe AbstractButton component. 
In addition, it describes the set of event listeners objects that are supported by all the different 
AbstractButton children. Its definition follows: 
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public interface ButtonModel extends ItemSelectable ( 
// Properties 
public String getActionCommand(); 
public void setActionCommand(String newValue); 
public boolean isArmed(); 
public void setArmed(boolean newValue); 
public boolean isEnabled(); 
public void setEnabled(boolean newValue); 
public void setGroup(ButtonGroup newValue); 
public int getMnemonic(); 
public void setMnemonic(int newValue); 
public boolean isPressed(); 
public void setPressed(boolean newValue); 
public boolean isRollover(); 
public void setRollover(boolean newValue); 
public boolean isSelected(); 
public void setSelected(boolean newValue); 
// Listeners 
public void addActionListener(ActionListener listener); 
public void removeActionListener(ActionListener listener); 
public void addChangeListener(Changelistener listener); 
public void removeChangeListener(ChangeListener listener); 
public void addItemListener(ItemListener listener); 
public void removeltemListener(ItemListener listener); 


The specific implementation of ButtonModel you'll use, unless you create your own, is the 
DefaultButtonModel class. The DefaultButtonModel class defines all the event registration 
methods for the different event listeners and manages the button state and grouping within 
a ButtonGroup. Its set of nine properties is shown in Table 4-12. They all come from the 
ButtonGroup interface, except selectedObjects, which is new to the DefaultButtonModel class, 
but more useful to the JToggleButton.ToggleButtonModel, which is discussed in Chapter 5. 


Table 4-12. DefaultButtonModel Properties 


Property Name Data Type Access 

actionCommand String Read-write 
armed boolean Read-write 
enabled boolean Read-write 
group ButtonGroup Read-write 
mnemonic int Read-write 
pressed boolean Read-write 
rollover boolean Read-write 
selected boolean Read-write 


selectedObjects Object[ ] Read-only 
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Most of the time, you don't access the ButtonModel directly. Instead, the components that 
use the ButtonModel wrap their property calls to update the model's properties. 


Note The DefaultButtonMode] also lets you get the listeners for a specific type with public 
EventListener[ ] getListeners(Class listenerType). 


Understanding AbstractButton Mnemonics 


A mnemonic is a special keyboard accelerator that when pressed causes a particular action to 
happen. In the case of the JLabel discussed earlier in the “JLabel Class” section, pressing the 
displayed mnemonic causes the associated component to get the input focus. In the case ofan 
AbstractButton, pressing the mnemonic for a button causes its selection. 

The actual pressing of the mnemonic requires the pressing of a look-and-feel-specific 
hotkey (the key tends to be the Alt key). So, if the mnemonic for a button were the B key, you 
would need to press Alt-B to activate the button with the B-key mnemonic. When the button is 
activated, registered listeners will be notified of appropriate state changes. For instance, with 
the JButton, all ActionListener objects would be notified. 

If the mnemonic key is part of the text label for the button, you'll see the character under- 
lined. This does depend on the current look and feel and could be displayed differently. In 
addition, if the mnemonic isn't part of the text label, there will not be a visual indicator for 
selecting the particular mnemonic key, unless the look and feel shows it in the tooltip text. 

Figure 4-11 shows two buttons: one with a W-key mnemonic, and the other with an H-key 
mnemonic. The left button has a label with Win its contents, so it shows the first Wunderlined. 
The second component doesn't benefit from this behavior on the button, but in the Ocean look 
and feel, identifies it only if the tooltip text is set and shown. 


le rnemenica A 


Warning Warning 


Hello ah 


Figure 4-11. AbstractButton mnemonics 


To assign a mnemonic to an abstract button, you can use either one of the setMnemonic() 
methods. One accepts a char argument and the other an int. Personally, I prefer the int variety, 
in which the value is one ofthe many VK_* constants from the KeyEvent class. You can also 
specify the mnemonic by position via the displayedMnemonicIndex property. 


AbstractButton button1 = new JButton("Warning"); 
button1.setMnemonic(KeyEvent.VK_W); 
content.add(button1); 
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Understanding AbstractButton Icons 


AbstractButton has seven specific icon properties. The natural or defaulticon is the icon prop- 
erty. Itis used for all cases unless a different icon is specified or there is a default behavior 
provided by the component. The selectedIcon property is the icon used when the button is 
selected. The pressedlIcon is used when the button is pressed. Which of these two icons is used 
depends on the component, because a JButton is pressed but not selected, whereas a 
JCheckBox is selected but not pressed. 

The disabledIcon and disabledSelectedIcon properties are used when the button has 
been disabled with setEnabled(false). By default, if the icon is an ImageIcon, a grayscaled 
version ofthe icon will be used. 

The remaining two icon properties, rolloverIcon and rolloverSelectedIcon, allow you to 
display different icons when the mouse moves over the button (and rolloverEnabled is true). 


Understanding Internal AbstractButton Positioning 


The horizontalAlignment, horizontalTextPosition, verticalAlignment, and 
verticalTextPosition properties share the same settings and behavior as the JLabel class. 
They're listed in Table 4-13. 


Table 4-13. AbstractButton Position Constants 


Position Property Available Settings 

horizontalAlignment LEFT, CENTER, RIGHT 
horizontalTextPosition LEFT, CENTER, RIGHT 
verticalAlignment TOP, CENTER, BOTTOM 
verticalTextPosition TOP, CENTER, BOTTOM 


Handling AbstractButton Events 


Although you do not create AbstractButton instances directly, you do create subclasses. 
All of them share a common set of event-handling capabilities. You can register 
PropertyChangeListener, ActionListener, ItemListener, and ChangeListener objects with 
abstract buttons. The PropertyChangeListener object will be discussed here, and the 
remaining objects listed will be discussed in later chapters, with the appropriate components. 
Like the JComponent class, the AbstractButton component supports the registering of 
PropertyChangeListener objects to detect when bound properties of an instance of the class 
change. Unlike the JComponent class, the AbstractButton component provides the following set 
of class constants to signify the different property changes: 


+ BORDER_PAINTED_CHANGED_ PROPERTY 


+ CONTENT_AREA FILLED CHANGED PROPERTY 


+ DISABLED ICON CHANGED PROPERTY 
+ DISABLED SELECTED_ICON CHANGED PROPERTY 


+ FOCUS PAINTED CHANGED PROPERTY 


CHAPTER 4 CORE SWING COMPONENTS 


+ HORIZONTAL _ALIGNMENT CHANGED PROPERTY 

+ HORIZONTAL _TEXT_ POSITION CHANGED PROPERTY 
+ ICON CHANGED PROPERTY 

+ MARGIN_ CHANGED PROPERTY 

+ MNEMONIC_CHANGED PROPERTY 

+ MODEL_CHANGED PROPERTY 

+ PRESSED_ ICON CHANGED PROPERTY 


+ ROLLOVER_ENABLED_ CHANGED PROPERTY 


+ ROLLOVER_TCON CHANGED PROPERTY 

+ ROLLOVER_SELECTED_1ICON_ CHANGED PROPERTY 
+ SELECTED_ICON CHANGED PROPERTY 

+ TEXT_CHANGED PROPERTY 

+ VERTICAL _ALTGNMENT_ CHANGED PROPERTY 

+ VERTICAL_TEXT_POSITION CHANGED PROPERTY 


Therefore, instead of hard-coding specific text strings, you can create a 
PropertyChangeListener that uses these constants, as shown in Listing 4-5. 


Listing 4-5. Base PropertyChangeListener for AbstractButton 


import javax.swing.*; 
import java.beans.*; 


public class AbstractButtonPropertyChangelistener 
implements PropertyChangeListener ( 


public void propertyChange(PropertyChangeEvent e) ( 
String propertyName = e.getPropertyName(); 
if (e.getPropertyName().equals(AbstractButton.TEXT_CHANGED PROPERTY)) ( 
String newText = (String) e.getNewValue(); 
String oldText = (String) e.getOldValue(); 
System.out.println(oldText + " changed to " + newText); 
j else if (e.getPropertyName().equals(AbstractButton.ICON CHANGED _PROPERTY)) £ 
Icon icon = (Icon) e.getNewValue(); 
if (icon instanceof Imagelcon) ( 
System.out.println("New icon is an image"); 
) 
) 
) 
J 
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JButton Class 


The JButton components the basic AbstractButton component that can be selected. It supports 
text, images, and HTML-based labels, as shown in Figure 4-12. 


nao same A 


Text Button AN 


Bufton 
Multi-line 


Figure 4-12. Sample JButton components 


Creating a JButton 


The JButton class has five constructors: 


public JButton() 
JButton button = new JButton(); 


public JButton(Icon image) 
Icon icon = new Imagelcon("dog.;jpg"); 
JButton button = new JButton(icon); 


public JButton(String text) 
JButton button = new JButton("Dog"); 


public JButton(String text, Icon icon) 
Icon icon = new Imagelcon("dog.;jpg"); 
JButton button = new JButton("Dog", icon); 


public JButton(Action action) 
Action action = ...; 
JButton button = new JButton(action); 


You can create a button with or without a text label oricon. The icon represents the default 
or selectedicon property from AbstractButton. 


Note Creating a JButton from an Action initializes the text label, icon, enabled status, and tooltip text. 
In addition, the ActionListener of the Action will be notified upon button selection. 
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JButton Properties 


The JButton component doesn't add much to the AbstractButton. As Table 4-14 shows, of the 
four properties of JButton, the only new behavior added is enabling the button to be the default. 


Table 4-14. JButton Properties 


Property Name Data Type Access 
accessibleContext AccessibleContext Read-only 
defaultButton boolean Read-only 
defaultCapable boolean Read-write bound 
UlClassID String Read-only 


The default button tends to be drawn with a different and darker border than the remaining 
buttons. When a button is the default, pressing the Enter key while in the top-level window 
causes the button to be selected. This works only as long as the component with the input 
focus, such as a text component or another button, doesn't consume the Enter key. Because 
the defaultButton property is read-only, how (you might be asking) do you set a button as the 
default? All top-level Swing windows contain a JRootPane, to be described in Chapter 8. You tell 
this JRootPane which button is the default by setting its defaultButton property. Only buttons 
whose defaultCapable property is true can be configured to be the default. Figure 4-13 shows 
the top-right button set as the default. 


[> Defautzatton AE 


Text Button AN 


| HTML 
A Warning | Button 
Multi-line 


Figure 4-13. Setting a default button 


Listing 4-6 demonstrates setting the default button component, as well as using a basic 
JButton. If the default button appearance doesn't seem that obvious in Figure 4-13, wait until 
the JOptionPane is described in Chapter 9, where the difference in appearance will be more 
obvious. Figure 4-13 uses a 2-by-2 GridLayout for the screen. The extra two arguments to the 
constructor represent gaps to help make the default button's appearance more obvious. 
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Listing 4-6. Configuring a Default Button 


import javax.swing.*; 
import java.awt.*; 
import java.awt.event.*; 


public class DefaultButton ( 


public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("DefaultButton"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


frame.setLayout(new GridlLayout(2, 2, 10, 10)); 


JButton button1 = new JButton("Text Button"); 
button1.setMnemonic(KeyEvent.VK_B); 
frame.add(button1); 


Icon warnIcon = new Imagelcon("Warn.gif"); 
JButton button2 = new JButton(warnIcon); 
frame.add(button2); 


JButton button3 = new JButton("Warning", warnIcon); 
frame.add(button3); 


String htmlButton = "<html><sup>HTML</sup> <sub><em>Button</em></sub><br>" + 
“<font color=1"HFFOO801"><u>Multi-line</u></font>"; 

JButton button4 = new JButton(htmlButton); 

frame.add(button4); 


JRootPane rootPane = frame.getRootPane(); 
rootPane.setDefaultButton(button2); 


frame.setSize(300, 200); 
frame.setVisible(true); 
y 
E 
EventQueue.invokeLater(runner); 
J 
) 


Handling JButton Events 


The JButton componentitself has no specific event-handling capabilities. They're all inherited 
from AbstractButton. Although you can listen for change events, item events, and property 
change events, the most helpful listener with the JButton is the ActionListener. 
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When the JButton components selected, all registered ActionListener objects are notified. 
When the button is selected, an ActionEvent is passed to each listener. This event passes along 
the actionCommand property of the button to help identify which button was selected when 
a shared listener is used across multiple components. Ifthe actionCommand property hasn't 
been explicitly set, the current text property is passed along instead. The explicit use of the 
actionCommand property is helpful with localization. Because the text property ofthe JButton is 
what the user sees, you as the handler of the button selection event listener cannot rely on a 
localized text label for determining which button was selected. So, while the text property can 
be localized so that a Yes button in English can say Sí in a Spanish version, if you explicitly set 
the actionCommand to be the "Yes" string, then no matter which language the useris running in, 
the actionCommand will remain "Yes" and not take on the localized text property setting. 

Listing 4-7 adds the event-handling capabilities to the default button example in Listing 4-6 
(see Figure 4-13). Notice that the default button behavior works properly: press Enter from any 
component, and button 2 (the default) will be activated. 


Listing 4-7. Watching Button Selection Events 


import javax.swing.*; 
import java.awt.*; 
import java.awt.event.*; 


public class ActionButtonSample ( 


public static void main(String args[]) ( 
Runnable runner = new Runnable() £ 
public void run() £ 
JFrame frame = new JFrame("DefaultButton"); 
frame.setDefaultClose0peration(JFrame.EXIT_ON CLOSE); 


ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
String command = actionEvent.getActionCommand(); 
System.out.println("Selected: " + command); 


) 
FS 


frame.setLayout(new GridLayout(2, 2, 10, 10)); 


JButton button1 = new JButton("Text Button"); 
button1.setMnemonic(KeyEvent.VK_B); 
button1.setActionCommand("First"); 
button1.addActionListener(actionListener); 
frame.add(button1); 


107 


108 CHAPTER 4 CORE SWING COMPONENTS 


Icon warnlcon = new Imagelcon("Warn.gif"); 
JButton button2 = new JButton(warnTcon); 
button2.setActionCommand("Second"); 
button2.addActionListener(actionListener); 
frame.add(button2); 


JButton button3 = new JButton("Warning", warnIcon); 
button3.setActionCommand("Third"); 
button3.addActionListener(actionListener); 
frame.add(button3); 


String htmlButton = "<html><sup>HTML</sup> <sub><em>Button</em></sub><br>" + 
“<font color=1"+HFFOO801"><u>»Multi-line</u></font>"; 

JButton button4 = new JButton(htmlButton); 

button4.setActionCommand("Fourth"); 

button4.addActionListener(actionListener); 

frame.add(button4); 


JRootPane rootPane = frame.getRootPane(); 
rootPane.setDefaultButton(button2); 


frame.setSize(300, 200); 
frame.setVisible(true); 
) 
y; 
EventQueue.invokeLater(runner); 
) 
) 


Customizing a JButton Look and Feel 


Each installable Swing look and feel provides a different JButton appearance and set of default 
UTResource value settings. Figure 4-14 shows the appearance ofthe JButton component for the 
preinstalled set of look and feel types: Motif, Windows, and Ocean. 


Motif LnF Dcean LnF 


Windows 


Figure 4-14. JButton under different look and feel types 
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The available set ofUTResource-related properties for a JButton is shown in Table 4-15. For 
the JButton component, there are 34 different properties. 


Table 4-15. Button UlResource Elements 
Property String 

Button.actionMap 

Button .background 

Button .border 
Button.contentAreaFilled 

Button. darkShadow 
Button.dashedRectGapHeight 
Button. dashedRectGapWidth 
Button. dashedRectGapX 
Button.dashedRectGapY 
Button.defaultButtonFollowsFocus 
Button.disabledForeground 
Button.disabledGrayRange 

Button. disabledShadow 
Button.disabledText 
Button.disabledToolBarBorderBackground 
Button.focus 

Button. focusInputMap 

Button. font 

Button. foreground 
Button.gradient 

Button.highlight 

Button. icon 

Button.iconTextGap 

Button. light 

Button.margin 

Button.rollover 
Button.rolloverIconType 
Button.select 


Button.shadow 


Button.showMnemonics 


Object Type 
ActionMap 
Color 
Border 
Boolean 
Color 
Integer 
Integer 
Integer 
Integer 
Boolean 
Color 
Integer[ ] 
Color 
Color 
Color 
Color 
InputMap 
Font 
Color 
List 
Color 
Icon 
Integer 
Color 
Insets 
Boolean 
String 
Color 
Color 


Boolean 
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Table 4-15. JButton UlResource Elements (Continued) 


Property String Object Type 
Button.textIconGap Integer 
Button.textshiftOffset Integer 
Button.toolBarBorderBackground Color 
ButtonUl String 


JPanel Class 


The last of the basic Swing components is the JPanel component. The JPanel component 
serves as both a general-purpose container object, replacing the AWT Panel container, and a 
replacement for the Canvas component, for those times when you need a drawable Swing 
component area. 


Creating a JPanel 
There are four constructors for JPanel: 
public JPanel() 


JPanel panel = new JPanel(); 


public JPanel(boolean isDoubleBuffered) 
JPanel panel = new JPanel(false); 


public JPanel(LayoutManager manager) 
JPanel panel = new JPanel(new GridLayout(2,2)); 


public JPanel(LayoutManager manager, boolean isDoubleBuffered) 
JPanel panel = new JPanel(new GridLayout(2,2), false); 


With the constructors, you can either change the default layout manager from FlowLayout 
or change the default double buffering that is performed from true to false. 


Using a JPanel 


You can use JPanel as your general-purpose container or as a base class for a new component. 
For the general-purpose container, the procedure is simple: Just create the panel, setits layout 
manager if necessary, and add components using the add() method. 


JPanel panel = new JPanel(); 

JButton okButton = new JButton("0K"); 

panel .add(okButton); 

JButton cancelButton = new JButton("Cancel"); 
panel.add(cancelButton); 
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When you want to create a new component, subclass JPanel and override the public void 
paintComponent (Graphics g) method. Although you can subclass JComponent directly, it seems 
more appropriate to subclass JPanel. Listing 4-8 demonstrates a simple component that draws 
an oval to fit the size of the component; it also includes a test driver. 


Listing 4-8. Oval Panel Component 


import java.awt.*; 
import javax.swing.*; 


public class OvalPanel extends JPanel £ 
Color color; 


public OvalPanel() £ 
this(Color.black); 
) 
public OvalPanel(Color color) ( 
this.color = color; 
) 
public void paintComponent(Graphics g) ( 
int width = getWidth(); 
int height = getHeight(); 
g.setColor(color); 
g.drawOval(0, O, width, height); 
) 


public static void main(String args[]) ( 
Runnable runner = new Runnable() 4 
public void run() £ 
JFrame frame = new JFrame("Oval Sample"); 
frame.setDefaultClose0peration(JFrame.EXIT_ON CLOSE); 


frame.setLayout(new GridLayout(2, 2)); 


Color colors[] = [Color.RED, Color.BLUE, Color.GREEN, Color.YELLOW?; 
for (int i=0; 1<4; i++) [ 

OvalPanel panel = new OvalPanel(colors[i]); 

frame.add(panel); 
) 


frame.setSize(300, 200); 
frame.setVisible(true); 
) 
E 


EventQueue.invokeLater(runner); 


111 


112 CHAPTER 4 CORE SWING COMPONENTS 


Figure 4-15 shows the test driver program results. 


lalx 


E 


Figure 4-15. The new OvalPanel component 


Note By default, JPanel components are opaque. This differs from JComponent, whose opacity 
property setting by default is false. A false setting for opacity means the component is transparent. 


Customizing a JPanel Look and Feel 


The available set ofUIResource-related properties for a JPanel is shown in Table 4-16. For the 
JPanel component, there are five different properties. These settings may have an effect on the 
components within the panel. 


Table 4-16. JPanel UlResource Elements 


Property String Object Type 
Panel.background Color 
Panel .border Border 
Panel. font Font 

Panel. foreground Color 
PanelUI String 
Summary 


In this chapter, you explored the root of all Swing components: the JComponent class. From 
there, you looked at some of the common elements of all components, such as tooltips, as well 
as specific components such as JLabel. You also learned how to put glyphs (nonverbal images) 
on components with the help of the Icon interface and the ImagelIcon class, and the GrayFilter 
image filter for disabled icons. 


CHAPTER 4 CORE SWING COMPONENTS 


You also learned about the AbstractButton component, which serves as the root compo- 
nent for all Swing button objects. You looked at its data model interface, ButtonModel, and the 
default implementation of this interface, DefaultButtonModel. Next, you looked at the JButton 
class, which is the simplest of the AbstractButton implementations. And lastly, you looked at 
the JPanel as the basic Swing container object. 

In Chapter 5, you'll start to diginto some ofthe more complex AbstractButton implemen- 


tations: the toggle buttons. 
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Toggle Buttons 


N ow that you've seen the capabilities of the relatively simple Swing components JLabel and 
JButton, it's time to take a look at more active components, specifically those that can be toggled. 
These so-called toggleable components—JToggleButton, JCheckBox, and JRadioButton—provide 
the means for your users to select from among a set of options. These options are either on or 
off, or enabled or disabled. When presented in a ButtonGroup, only one of the options in the 
group can be selected at a time. To deal with this selection state, the components share a common 
data model with ToggleButtonMode1. Let's take a look at the data model, the components' 
grouping mechanism with ButtonGroup, and the individual components. 


ToggleButtonModel Class 


The JToggleButton. ToggleButtonModel class is a public inner class of JToggleButton. The class 
customizes the behavior ofthe DefaultButtonModel class, which, in turn, is an implementation 
ofthe ButtonModel interface. 

The customization affects the data models of all AbstractButton components in the 
same ButtonGroup—a class explored next. In short, a ButtonGroup is a logical grouping of 
AbstractButton components. At any one time, only one ofthe AbstractButton components 
in the ButtonGroup can have the selected property of its data model set to true. The remaining 
ones must be false. This does not mean that only one selected component in the group can 
exist at a time. If multiple components in a ButtonGroup share a ButtonModel, multiple selected 
components in the group can exist. If no components share a model, at most, the user can 
select one component in the group. Once the user has selected that one component, the user 
cannot interactively deselect the selection. However, programmatically, you can deselect all 
group elements. 

The definition of JToggleButton.ToggleButtonModel follows. 


public class ToggleButtonModel extends DefaultButtonModel ( 
// Constructors 
public ToggleButtonModel (); 
// Properties 
public boolean isSelected(); 
public void setPressed(boolean newValue); 
public void setSelected(boolean newvalue); 
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The ToggleButtonModel class defines the default data model for both the JToggleButton 
and its subclasses JCheckBox and JRadioButton, described in this chapter, as well as the 
JCheckBoxMenuTtem and JRadioButtonMenuTtem classes described in Chapter 6. 


Note Internally, Swing's HTML viewer component uses the ToggleButtonModel for its check box and 
radio button input form elements. 


ButtonGroup Class 


Before describing the ButtonGroup class, let's demonstrate its usage. The program shown in 
Listing 5-1 creates objects that use the ToggleButtonModel and places them into a single group. 
As the program demonstrates, in addition to adding the components into the screen's container, 
you must add each component to the same ButtonGroup. This results in a pair of add() method 
calls for each component. Furthermore, the container for the button group tends to place 
components in a single column and to label the grouping for the user with a titled border, 
though neither of these treatments are required. Figure 5-1 shows the output of the program. 


Listing 5-1. Odd Collection of Button Components 


import javax.swing.*; 
import javax.swing.border.*; 
import java.awt.*; 


public class AButtonGroup ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("Button Group”); 
frame.setDefaultClose0peration(JFrame.EXIT_ON CLOSE); 
JPanel panel = new JPanel(new GridLayout(0, 1)); 
Border border = 
BorderFactory.createTitledBorder("Examples"); 
panel.setBorder(border); 
ButtonGroup group = new ButtonGroup(); 
AbstractButton abstract1 = 
new JToggleButton("Toggle Button"); 
panel.add(abstract1); 
group.add(abstract1); 
AbstractButton abstract2 = 
new JRadioButton("Radio Button"); 
panel.add(abstract2); 
group.add(abstract2); 
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AbstractButton abstract3 = 
new JCheckBox("Check Box"); 
panel.add(abstract3); 
group.add(abstract3); 
AbstractButton abstract4 = 
new JRadioButtonMenultem("Radio Button Menu Item"); 
panel.add(abstract4); 
group.add(abstract4); 
AbstractButton abstract5 = 
new JCheckBoxMenultem("Check Box Menu Item"); 
panel.add(abstract5); 
group.add(abstract5); 
frame.add(panel, BorderLayout.CENTER); 
frame.setSize(300, 200); 
frame.setVisible(true); 
y 
E 
EventQueue.invokelLater(runner); 
) 
J 


[2 tattoncroso A 


Examples 


| Toggle Button 


(O Radio Button 


Check Box 


O Radio Button Menu Item 


[Mi Check Box Menu Item 


Figure 5-1. ButtonGroup/ToggleButtonModel example 


As previously stated, the ButtonGroup class represents a logical grouping of AbstractButton 
components. The ButtonGroup is not a visual component; therefore, there's nothing visual on 
screen when a ButtonGroup is used. Any AbstractButton component can be added to the grouping 
with public void add(AbstractButton abstractButton). Although any AbstractButton 
component can belong to a ButtonGroup, only when the data model for the component is 
ToggleButtonModel will the grouping have any effect. The result of having a component with a 
data model of ToggleButtonModel in a ButtonGroup is that after the component is selected, the 
ButtonGroup deselects any currently selected component in the group. 


Note Technically speaking, the model doesn't need to be ToggleButtonModel] as long as the custom 
model exhibits the same behavior of limiting the number of selected component models to one. 
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Although the add() method is typically the only ButtonGroup method you'll ever need, the 
following class definition shows that it's not the only method of ButtonGroup in existence: 


public class ButtonGroup implements Serializable ( 
// Constructor 
public ButtonGroup(); 
// Properties 
public int getButtonCount(); 
public Enumeration getElements(); 
public ButtonModel getSelection(); 
// Other methods 
public void add(AbstractButton aButton); 
public boolean isSelected(ButtonModel theModel) ; 
public void remove(AbstractButton aButton); 
public void setSelected(ButtonModel theModel, boolean newValue); 


One interesting thing the class definition shows is that given a ButtonGroup, you cannot 
directly find out the selected AbstractButton. You can directly ask only which ButtonModel is 
selected. However, getElements() returns an Enumeration ofall the AbstractButton elements in 
the group. You can then loop through all the buttons to find the selected one (or ones) by using 
code similar to the following: 


Enumeration elements = group.getElements(); 
while (elements.hasMoreElements()) f 
AbstractButton button = (AbstractButton)elements.nextElement(); 
if (button.isSelected()) f 
System.out.println("The winner is: " + button.getText()); 
break; // Don't break if sharing models -- could show multiple buttons selected 
J 
) 


The other interesting method of ButtonGroup is setSelected(). The two arguments of the 
method are a ButtonModel and a boolean. If the boolean value is false, the selection request is 
ignored. Ifthe ButtonModel isn't the model for a button in the ButtonGroup, then the ButtonGroup 
deselects the currently selected model, causing no buttons in the group to be selected. The 
proper usage ofthe method is to call the method with a model ofa component in the group and 
a new state of true. For example, ifaButton is an AbstractButton and aGroup is the ButtonGroup, 
then the method call would look like aGroup.setSelected(aButton.getModel(), true). 


Note If you add a selected button to a ButtonGroup that already has a previously selected button, the 
previous button retains its state and the newly added button loses ¡ts selection. 


Now, let's look at the various components whose data model is the ToggleButtonModel. 
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JToggleButton Class 


The JToggleButton is the first of the toggleable components. It's discussed first because it's 
the parent class of the two other components that are not menu-oriented: JCheckBox and 
JRadioButton. The JToggleButton is like a JButton that stays depressed when selected, instead 
of bouncing back to an unselected state. To deselect the selected component, you must reselect it. 
JToggleButton isn't a commonly used component, but you might find it useful on a toolbar, 
such as in Microsoft Word (for paragraph alignment, among other instances) or in a file dialog 
box, as shown in the upper-right corner of Figure 5-2. 


JToggleButton 
y e 

Look In: [C7 jak41.5.0 >| (A 15 10 ada 
(3 bin (3 sample Bn src.zip 
1 demo (1 sre [Ey THIRDA 
E docs [y COPYRIGHT 
E include E LICENSE 
EJ jre EY LICENSE.rtf 
(3 lib E) README.html 
[4] »| 
File Name: — || 
Files of Type: ¡All Files wv 


Open Cancel 


Figure 5-2. Sample JToggleButton components from file chooser 


Defining the JToggleButton structure are two objects that customize the AbstractButton 
parent class: ToggleButtonModel and ToggleButtonUI. The ToggleButtonModel class represents 


a customized ButtonModel data model for the component, whereas ToggleButtonUl is the user 
interface delegate. 


Now that you know about the different pieces ofa JToggleButton, let's find out how to 
use them. 


Creating JToggleButton Components 
Eight constructors are available for JToggleButton: 
public JToggleButton() 

JToggleButton aToggleButton = new JToggleButton(); 


public JToggleButton(Icon icon) 
JToggleButton aToggleButton = new JToggleButton(new DiamondIcon(Color.PINK)) 
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public JToggleButton(Icon icon, boolean selected) 
JToggleButton aToggleButton = new JToggleButton(new DiamondIcon(Color.PINK), true); 


public JToggleButton(String text) 
JToggleButton aToggleButton = new JToggleButton("Sicilian"); 


public JToggleButton(String text, boolean selected) 


JToggleButton aToggleButton = new JToggleButton("Thin Crust", true); 


public JToggleButton(String text, Icon icon) 
JToggleButton aToggleButton = new JToggleButton("Thick Crust", 
new DiamondIcon(Color.PINK)); 


public JToggleButton(String text, Icon icon, boolean selected) 
JToggleButton aToggleButton = new JToggleButton("Stuffed Crust”, 
new DiamondIcon(Color.PINK), true); 


public JToggleButton(Action action) 
Action action = ...; 
JToggleButton aToggleButton = new JToggleButton(action); 


Each allows you to customize one or more of the label, icon, or initial selection state. 
Unless specified otherwise, the label is empty with no text or icon, and the button initially is 
not selected. 


Note Surprisingly, Swing lacks a constructor that accepts only an initial state of a boolean setting. 
Lacking this constructor, you need to create a JToggleButton with the no-argument constructor variety, 
and then call setSelected(boolean newValue) directly or work with an Action. 


JToggleButton Properties 


After creating a JToggleButton, you can modify each of its many properties. Although there are 
about 100 inherited properties, Table 5-1 shows only the two introduced with JToggleButton. 
The remaining properties come from AbstractButton, JComponent, Container, and Component. 


Table 5-1. JToggleButton Properties 


Property Name Data Type Access 
accessibleContext AccessibleContext Read-only 
UlClassID String Read-only 


You can change one or more of the text, icon, or selected properties set in the constructor, 
as well as any of the other AbstractButton properties described in Chapter 4. You configure 
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the primary three properties with the appropriate getter and setter methods: get/setText(), 
get/setIcon(), and is/setSelected(), or setAction(action). The other properties have corre- 
sponding getter and setter methods. 

The more visual configurable options of JToggleButton (and its subclasses) include the 
various icons for the different states of the button. Besides the standard icon, you can display 
a different icon when the button is selected, among other state changes. However, ifyou're 
changing icons based on the currently selected state, then JToggleButton probably isn't the 
most appropriate component to use. You should use one of its subclasses, JCheckBox or 
JRadioButton, explored later in this chapter. 


Note Keep in mind that the JButton component ignores the selectedIcon property. 


Handling JToggleButton Selection Events 


After configuring a JToggleButton, you can handle selection events in one of three ways: with 
an ActionListener, an ItemListener, or a ChangeListener. This is in addition to providing an 
Action to the constructor, which would be notified like an ActionListener. 


Listening to JToggleButton Events with an ActionListener 


Il you're interested only in what happens when a user selects or deselects the JToggleButton, 
you can attach an ActionListener to the component. After the user selects the button, the 
component notifies any registered ActionListener objects. Unfortunately, this isn't the desired 
behavior, because you must then actively determine the state of the button so that you can 
respond appropriately for selecting or deselecting. To find out the selected state, you must get 
the model for the event source, and then ask for its selection state, as the following sample 
ActionListener source shows: 


ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
AbstractButton abstractButton = (AbstractButton)actionEvent.getSource(); 
boolean selected = abstractButton.getModel().isSelected(); 
System.out.println("Action - selected=" + selected + "Y n"); 
) 
A 


Listening to JToggleButton Events with an ItemListener 


The better listener to attach to a JToggleButton is the ItemListener. The ItemEvent passed to 
the itemStateChanged() method of ItemListener includes the current selection state of the 
button. This allows you to respond appropriately, without needing to search for the current 
button state. 

To demonstrate, the following ItemListener reports the state of a selected ItemEvent- 
generating component: 
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ItemListener itemListener = new ItemListener() f 
public void itemStateChanged(ItemEvent itemEvent) £ 
int state = itemEvent.getStateChange(); 
if (state == ItemEvent.SELECTED) f 
System.out.println("Selected"); 
+ else [ 
System.out.println("Deselected"); 
) 
J 
5 


Listening to JToggleButton Events with a ChangeListener 


Attaching a ChangeListener to a JToggleButton provides even more flexibility. Any attached 
listener will be notified ofthe data model changes for the button, corresponding to changes in 
its armed, pressed, and selected properties. Listening for notification from the three listeners— 
ActionListener, ItemListener, and ChangeListener—allows you to react seven different times. 
Figure 5-3 shows the sequencing of the ButtonModel property changes, and when the model 


notifies each of the listeners. 
] JToggleButton 7 ChangeListener |Ttentistener ActionListener 


Mouse Pressed, armed=true 
| pressed=trué si 


ButtonModel 


Mouse Released selectedotrue BEE 
2, 
pressed=false S 
co E 
armed=false Y 
y, 


Figure 5-3. JToggleButton notification sequencing diagram 


selected EE 
activated XA 


To demonstrate the ChangeListener notifications, the following code fragment defines a 
ChangeListener that reports the state changes to the three properties of the button model: 


Changelistener changeListener = new ChangeListener() ( 
public void stateChanged(ChangeEvent changeEvent) ( 
AbstractButton abstractButton = (AbstractButton)changeEvent.getSource(); 
ButtonModel buttonModel = abstractButton.getModel (); 
boolean armed = buttonModel.isArmed(); 
boolean pressed = buttonModel.isPressed(); 
boolean selected = buttonModel.isSelected(); 
System.out.println("Changed: " + armed + "/" + pressed + "/" + selected); 


E; 
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After you attach the ChangeListener to a JToggleButton and select the component by 
pressing and releasing the mouse over the component, the following output results: 


Changed: true/false/false 
Changed: true/true/false 
Changed: true/true/true 

Changed: true/false/true 
Changed: false/false/true 


With all three listeners attached to the same button, notification of registered ItemListener 
objects would happen after the selected property changes—in other words, between lines 3 
and 4. Listing 5-2 demonstrates all three listeners attached to the same JToggleButton. With 
regard to the registered ActionListener objects, notification happens after releasing the button, 
but before the armed state changes to false, falling between lines 4 and 5. 


Listing 5-2. Listening for Toggle Selection 


import javax.swing.*; 
import javax.swing.event.*; 
import java.awt.*; 

import java.awt.event.*; 


public class SelectingToggle ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() 4 
public void run() £ 
JFrame frame = new JFrame("Selecting Toggle"); 
frame.setDefaultClose0peration(JFrame.EXIT_ON CLOSE); 
JToggleButton toggleButton = new JToggleButton("Toggle Button"); 
// Define ActionListener 
ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
AbstractButton abstractButton = (AbstractButton)actionEvent.getSource(); 
boolean selected = abstractButton.getModel().isSelected(); 
System.out.println("Action - selected=" + selected + "n"); 
J 
E 
// Define ChangeListener 
Changelistener changelistener = new ChangeListener() ( 
public void stateChanged(ChangeEvent changeEvent) ( 
AbstractButton abstractButton = (AbstractButton)changeEvent.getSource(); 
ButtonModel buttonModel = abstractButton.getModel (); 
boolean armed = buttonModel.isArmed(); 
boolean pressed = buttonModel.isPressed(); 
boolean selected = buttonModel.isSelected(); 
System.out.println("Changed: " + armed + "/" + pressed + "/" + 
selected); 


$; 
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// Define ItemListener 
ItemListener itemListener = new ItemListener() f 
public void itemStateChanged(ItemEvent itemEvent) ( 
int state = itemEvent.getStateChange(); 
if (state == ItemEvent.SELECTED) 4 
System.out.println("Selected"); 
y else [ 
System.out.println("Deselected"); 
J 
J 
p; 
// Attach Listeners 
toggleButton.addActionListener(actionListener); 
toggleButton.addChangeListener(changeListener); 
toggleButton.addItemListener(itemListener); 
frame.add(toggleButton, BorderLayout .NORTH); 
frame.setSize(300, 125); 
frame.setVisible(true); 
Í 
; 
EventQueue.invokeLater (runner); 
J 
y 


Customizing a JToggleButton Look and Feel 


Each installable Swing look and feel provides a different JToggleButton appearance and set of 
default UIResource values. Figure 5-4 shows the appearance of the JToggleButton component 
for the preinstalled set of look and feel types: Motif, Windows, and Ocean. As the button labels 
might indicate, the first button is selected, the second has the input focus (and isn't selected), 
and the third button isn't selected. 


lx ALTE 
Focused | Focused | 
Not Selected 
Motif Windows 
=10/x] 
Saeta | 
Focused 
Not Selected | 


Ocean 


Figure 5-4. JToggleButton under different look and feel types 
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The available set ofUIResource-related properties for a JToggleButton is shown in Table 5-2. 
The JToggleButton component has 17 different properties. 


Table 5-2. JToggleButton UlResource Elements 


Property String 


Toggle 
Toggle 
Toggle 
Toggle 
Toggle 
Toggle 
Toggle 
Toggle 
Toggle 
Toggle 
Toggle 
Toggle 
Toggle 
Toggle 
Toggle 
Toggle 


Toggle 


JCheckBox Class 


Button. 
Button. 
Button. 
Button. 
Button. 
Button 
Button. 
Button. 
Button. 
Button. 
Button. 
Button. 
Button. 
Button. 
Button. 
Button. 


background 
border 
darkShadow 
disabledText 


focus 


«focusInputMap 


font 
foreground 
gradient 
highlight 
light 
margin 
select 
shadow 


textIconGap 


textShiftOffset 
ButtonUl 


Object Type 
Color 
Border 
Color 
Color 
Color 
Object[ ] 
Font 

Color 

List 
Color 
Color 
Insets 


Color 


Color 
Integer 
Integer 


String 


The JCheckBox class represents the toggle component that, by default, displays a check box 
icon next to the text label for a two-state option. The check box icon uses an optional check 
mark to show the current state of the object, instead of keeping the button depressed, as with 
the JToggleButton. With the JCheckBox, the icon shows the state ofthe object, whereas with the 
JToggleButton, the icon is part of the label and isn't usually used to show state information. 
With the exception of the Ul-related differences between JCheckBox and JToggleButton, the 
two components are identical. Figure 5-5 demonstrates how check box components might 
appear in a pizza-ordering application. 
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Figure 5-5. Sample JCheckBox components 


The JCheckBox is made up of several pieces. Like JToggleButton, the JCheckBox uses a 
ToggleButtonModel to represent its data model. The user interface delegate is CheckBoxUI. 
Although the ButtonGroup is available to group together check boxes, it isn't normally appropriate. 
When multiple JCheckBox components are within a ButtonGroup, they behave like JRadioButton 
components but look like JCheckBox components. Because of this visual irregularity, you 
shouldn't put JCheckBox components into a ButtonGroup. 

Now that you've seen the different pieces of a JCheckBox, let's find out how to use them. 


Creating JCheckBox Components 


Eight constructors exist for JCheckBox: 


public JCheckBox() 
JCheckBox aCheckBox = new JCheckBox(); 


public JCheckBox(Icon icon) 
JCheckBox aCheckBox = new JCheckBox(new DiamondIcon(Color.RED, false)); 
aCheckBox.setSelectedIcon(new DiamondIcon(Color.PINK, true)); 


public JCheckBox(Icon icon, boolean selected) 
JCheckBox aCheckBox = new JCheckBox(new DiamondIcon(Color.RED, false), true); 
aCheckBox.setSelectedIcon(new DiamondIcon(Color.PINK, true)); 


public JCheckBox(String text) 
JCheckBox aCheckBox = new JCheckBox("Spinach"); 


public JCheckBox(String text, boolean selected) 
JCheckBox aCheckBox = new JCheckBox("Onions", true); 


public JCheckBox(String text, Icon icon) 
JCheckBox aCheckBox = new JCheckBox("Garlic", new DiamondIcon(Color.RED, false)); 
aCheckBox.setSelectedIcon(new DiamondIcon(Color.PINK, true)); 
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public JCheckBox(String text, Icon icon, boolean selected) 

JCheckBox aCheckBox = new JCheckBox("Anchovies", new DiamondIcon(Color.RED, 
false), true); 

aCheckBox.setSelectedIcon(new DiamondIcon(Color.PINK, true)); 


public JCheckBox(Action action) 
Action action = ...; 
JCheckBox aCheckBox = new JCheckBox(action); 


Note Configuring a JCheckBox from an Action sets the label, state, and tooltip text, but not the icon. 


Each allows you to customize either none or up to three properties for the label, icon, or 
initial selection state. Unless specified otherwise, there's no text in the label and the default 
selected/unselected icon for the check box appears unselected. 

If you do initialize the icon in the constructor, it's the icon for the unselected state of the 
check box, with the same icon displayed when the check box is selected. You must also either 
initialize the selected icon with the setSelectedIcon(Icon newValue) method, described later, 
or make sure the icon is state-aware and updates itself. Ifyou don't configure the selected icon 
and don't use a state-aware icon, the same icon will appear for both the selected and unselected 
state. Normally, an icon that doesn't change its visual appearance between selected and unse- 
lected states isn't desirable for a JCheckBox. 


Note A state-aware icon is one that asks the associated component for the value of the selected 
property. 


JCheckBox Properties 


After creating a JCheckBox, you can modify each of its many properties. Two properties specific 
to JCheckBox (shown in Table 5-3) override the behavior of its parent JToggleButton. The third 
borderPaintedFlat property was introduced in the 1.3 release of the JDK. All the remaining 
properties are inherited through parents of JToggleButton. 


Table 5-3. JCheckBox Properties 


Property Name Data Type Access 
accessibleContext AccessibleContext Read-only 
borderPaintedFlat boolean Read-write bound 


UlClassID String Read-only 


127 


128 


CHAPTER 5 TOGGLE BUTTONS 


The borderPaintedFlat property permits a look and feel to display the border around 
the check icon as two-dimensional (flat) instead of three-dimensional. By default, the 
borderPaintedFlat property is false, meaning the border will be three-dimensional. Figure 5-6 
shows what a flat border looks like, where the first, third, and fifth borders are flat, and the 
second and fourth are not. A look and feel may choose to ignore this property. However, it is 
useful for renderers for components such tables and trees, where they show only state and are 
not selectable. The Windows and Motif look and feel types take advantage of the property; 
Metal (and Ocean) does not. 


£ Flat CheckBox Sample =10/xÍ 


Pizza Toppings 


Anchovies 


[Y Garlic 


TF Pepperoni 


Spinach 
Submit 


Figure 5-6. Alternating flat JCheckBox borders for the Windows look and feel: Anchovies, Onions, 
and Spinach are flat; Garlic and Pepperoni are not. 


As the constructor listing demonstrated, if you choose to set an icon with a constructor, 
the constructor sets only one icon for the unselected state. If you want the check box icon to 
show the correct state visually, you must use a state-aware icon or associate a differenticon for 
the selected state with setSelectedIcon(). Having two different visual state representations is 
what most users expect from a JCheckBox, so unless you have a good reason to do otherwise, it's 
best to follow the design convention for normal user interfaces. 

The fourth button at the bottom of the screen shown in Figure 5-7 demonstrates confusing 
icon usage within a JCheckBox. The check box always appears selected. The figure displays what 
the screen looks like with Pizza selected, Calzone unselected, Anchovies unselected, and Stuffed 
Crust unselected (although the last one appears selected). 


lolxl 
4 Pizza 
< Calzone 


de Anchovies 


4 Stuffed Crust 


Figure 5-7. Multiple JCheckBox components with various icons 
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Listing 5-3 demonstrates three valid means of creating JCheckBox components with 
different icons, one using a state-aware icon. The last check box shows bad icon usage. 


Listing 5-3. Sampling JCheckBox 


import javax.swing.*; 
import java.awt.*; 
import java.awt.event.*; 


public class IconCheckBoxSample ( 
private static class CheckBoxIcon implements Icon ( 
private Imagelcon checkedIcon = new Imagelcon("Plus.gif"); 
private Imagelcon uncheckedIcon = new Imagelcon("Minus.gif"); 


public void paintIcon(Component component, Graphics g, int x, int y) ( 
AbstractButton abstractButton = (AbstractButton)component; 
ButtonModel buttonModel = abstractButton.getModel (); 
g-translate(x,y); 
Imagelcon imagelcon = buttonModel.isSelected() ? 
checkedIcon : uncheckedIcon; 
Image image = imagelcon.getImage(); 
g-drawImage(image, 0, O, component); 
g-translate(-x,-y); 
4 
public int getIconWidth() ( 
return 20; 
y 
public int getIconHeight() ( 
return 20; 
h 
) 
public static void main(String args[]) ( 
Runnable runner = new Runnable() 4 
public void run() £ 
JFrame frame = new JFrame("Iconizing CheckBox"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
Icon checked = new DiamondIcon (Color.BLACK, true); 
Icon unchecked = new DiamondIcon (Color.BLACK, false); 
JCheckBox aCheckBox1 = new JCheckBox("Pizza", unchecked); 
aCheckBox1.setSelectedIcon(checked); 
JCheckBox aCheckBox2 = new JCheckBox("Calzone"); 
aCheckBox2.setIcon(unchecked) ; 
aCheckBox2.setSelectedIcon(checked); 
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Icon checkBoxIcon = new CheckBoxIcon(); 
JCheckBox aCheckBox3 = new JCheckBox("Anchovies", checkBoxIcon); 
JCheckBox aCheckBox4 = new JCheckBox("Stuffed Crust", checked); 
frame.setLayout(new GridLayout(0,1)); 
frame.add(aCheckBox1); 
frame.add(aCheckBox2); 
frame.add(aCheckBox3); 
frame.add(aCheckBox4); 
frame.setSize(300, 200); 
frame.setVisible(true); 
hi 
E 
EventQueue.invokeLater(runner); 


J 


Handling JCheckBox Selection Events 


As with the JToggleButton, you can handle JCheckBox events in any one of three ways: with an 
ActionListener, an ItemListener, or a ChangeListener. The constructor that accepts an Action 
just adds the parameter as an ActionListener. 


Listening to JCheckBox Events with an ActionListener 


Subscribing to ActionEvent generation with an ActionListener allows you to find out when the 
user toggles the state of the JCheckBox. As with JToggleButton, the subscribed listener is told of 
the selection, but not the new state. To find out the selected state, you must get the model for the 
event source and ask, as the following sample ActionListener source shows. This listener 
modifies the check box label to reflect the selection state. 


ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) f 
AbstractButton abstractButton = (AbstractButton)actionEvent.getSource(); 
boolean selected = abstractButton.getModel().isSelected(); 
String newlLabel = (selected ? SELECTED_LABEL : DESELECTED_LABEL); 
abstractButton.setText(newLabel); 
y 
5 


Listening to JCheckBox Events with an ItemListener 


For JCheckBox, as with JToggleButton, the better listenerto subscribe to is an ItemListener. The 
ItemEvent passed to the itemStateChanged() method of ItemListener includes the current 
state of the check box. This allows you to respond appropriately, without need to find out the 
current button state. 

To demonstrate, the following ItemListener swaps the foreground and background colors 
based on the state of a selected component. In this ItemListener, the foreground and back- 
ground colors are swapped only when the state is selected. 
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ItemListener itemlListener = new ItemListener() f 
public void itemStateChanged(ItemEvent itemEvent) ( 
AbstractButton abstractButton = (AbstractButton)itemEvent.getSource(); 
Color foreground = abstractButton.getForegrouna(); 
Color background = abstractButton.getBackgrouna(); 
int state = itemEvent.getStateChange(); 
if (state == ItemEvent.SELECTED) £ 
abstractButton.setForeground(background) |; 
abstractButton.setBackground(foreground); 
y 
J 
5 


Listening to JCheckBox Events with a ChangeListener 


The ChangeListener responds to the JCheckBox just as with the JToggleButton. A subscribed 
ChangeListener would be notified when the button is armed, pressed, selected, or released. 
In addition, the ChangeL istener is also notified of changes to the ButtonModel, such as for the 
keyboard mnemonic (KeyEvent .VK_S) ofthe check box. Because there are no ChangeListener 
differences to demonstrate between a JToggleButton and a JCheckBox, you could just attach the 
same listener from JToggleButton to the JCheckBox, and you'll get the same selection responses. 

The sample program in Listing 5-4 demonstrates all the listeners subscribed to the events 
of a single JCheckBox. To demonstrate that the ChangeListener is notified of changes to other 
button model properties, a keyboard mnemonic is associated with the component. Given that 
the ChangeListener is registered before the memonic property is changed, the ChangeListener 
is notified of the property change. Because the foreground and background colors and text 
label aren't button model properties, the ChangeListener isn't told of these changes made by 
the other listeners. 


Note If you did want to listen for changes to the foreground or background color properties, you would 
need to attach a PropertyChangeListener to the JCheckBox. 


Listing 5-4. Listening for JCheckBox Selection 


import javax.swing.*; 
import javax.swing.event.*; 
import java.awt.*; 

import java.awt.event.*; 


public class SelectingCheckBox ( 
private static String DESELECTED_LABEL = "Deselected"; 
private static String SELECTED_LABEL = "Selected"; 
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public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("Selecting CheckBox"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
JCheckBox checkBox = new JCheckBox(DESELECTED LABEL); 
// Define ActionListener 
ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
AbstractButton abstractButton = 
(AbstractButton)actionEvent.getSource(); 
boolean selected = abstractButton.getModel().isSelected(); 
String newlabel = (selected ? SELECTED_LABEL : DESELECTED_LABEL); 
abstractButton.setText(newLabel); 
h 
E 
// Define ChangeListener 
Changelistener changeListener = new Changelistener() ( 
public void stateChanged(ChangeEvent changeEvent) ( 
AbstractButton abstractButton = 
(AbstractButton)changeEvent.getSource(); 
ButtonModel buttonModel = abstractButton.getModel(); 
boolean armed = buttonModel.isArmed(); 
boolean pressed = buttonModel.isPressed(); 
boolean selected = buttonModel.isSelected(); 
System.out.println("Changed: " + armed + "/" + pressed + "/" + 
selected); 
h 
E 
// Define ItemListener 
ItemListener itemlListener = new ItemListener() f 
public void itemStateChanged(ItemEvent itemEvent) ( 
AbstractButton abstractButton = 
(AbstractButton)itemEvent.getSource(); 
Color foreground = abstractButton.getForeground(); 
Color background = abstractButton.getBackground(); 
int state = itemEvent.getStateChange(); 
if (state == ItemEvent.SELECTED) 4 
abstractButton.setForeground(background); 
abstractButton.setBackground(foreground); 
J 
) 
E 
// Attach Listeners 
checkBox.addActionListener(actionListener); 
checkBox.addChangeListener(changeListener); 
checkBox.addItemListener(itemListener); 
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checkBox.setMnemonic(KeyEvent.VK_S); 
frame.add(checkBox, BorderLayout .NORTH); 
frame.setSize(300, 100); 
frame.setVisible(true); 
) 
y; 
EventQueue.invokeLater(runner); 
) 
) 


The SelectingCheckBox class produces the screen shown in Figure 5-8, after selecting and 
deselecting the JCheckBox. 


í Selecting CheckBox 101 xÍ 
Ml Deselected 


Figure 5-8. SelectingCheckBox program screen 


Customizing a JCheckBox Look and Feel 


Each installable Swing look and feel provides a different JCheckBox appearance and set of 
default UIResource values. Figure 5-9 shows the appearance of the JCheckBox component for 


the preinstalled set of look and feel types: Motif, Windows, and Ocean. The first, third, and fifth 
check boxes are selected; the third has the input focus. 


Jolx -lolxl 
Pizza Toppings ¡Pizza Toppings 
WM Anchovies | [Y Anchovies 
—JGarlic  Garlic 
MiOnions vÚ 
-—JPepperoni 


Mópinach 7 Pepperori 
nac! 
al [Y Spinach 


Motif Windows 
lolx] 
Pizza Toppings 


|] Anchovies 
[] Garlic 

[y] Onions 

| /Pepperoni 


[v] Spinach 


Submit 


Ocean 


Figure 5-9. JCheckBox under different look and feel types 
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Table 5-4 shows the set of available UIResource-related properties for a JCheckBox. The 
JCheckBox component has 20 different properties. 


Table 5-4. JCheckBox UlResource Elements 


Property String Object Type 
CheckBox.background Color 
CheckBox.border Border 
CheckBox.darkShadow Color 
CheckBox.disabledText Color 
CheckBox. focus Color 
CheckBox.focusInputMap Object[ ] 
CheckBox. font Font 
CheckBox. foreground Color 
CheckBox.gradient List 
CheckBox.highlight Color 
CheckBox.icon Icon 
CheckBox.interiorBackground Color 
CheckBox. light Color 
CheckBox.margin Insets 
CheckBox.rollover Boolean 
Checkbox.select* Color 
CheckBox. shadow Color 
CheckBox.textIconGap Integer 
CheckBox.textShiftOffset Integer 
CheckBoxUI String 


* Lowercase b is correct. 


JRadioButton Class 


You use JRadioButton when you want to create a mutually exclusive group of toggleable 
components. Although, technically speaking, you could place a group of JCheckBox components 
into a ButtonGroup and only one would be selectable at a time, they wouldn't look quite right. 
At least with the predefined look and feel types, JRadioButton and JCheckBox components look 
different, as Figure 5-10 shows. This difference in appearance tells the end user to expect 
specific behavior from the components. 
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Jolxi 
Radio Buttons Check Boxes 
O 4 slices y] Anchovies 
(8) 8 slices ] Garlic 
O 12 slices [] Onions 
O 16 slices y] Spinach 


Figure 5-10. Comparing JRadioButton to JCheckBox appearance 


The JRadioButton is made up of several pieces. Like JToggleButton and JCheckBox, the 
JRadioButton uses a ToggleButtonModel to represent its data model. It uses a ButtonGroup 
through AbstractButton to provide the mutually exclusive grouping, and the user interface 
delegate is the RadioButtonUl. 

Let's now explore how to use the different pieces of a JRadioButton. 


Creating JRadioButton Components 


As with JCheckBox and JToggleButton, there are eight constructors for JRadioButton: 


public JRadioButton() 
JRadioButton aRadioButton = new JRadioButton(); 


public JRadioButton(Icon icon) 
JRadioButton aRadioButton = new JRadioButton(new DiamondIcon(Color.CYAN, false)); 
aRadioButton.setSelectedIcon(new DiamondIcon(Color.BLUE, true)); 


public JRadioButton(Icon icon, boolean selected) 

JRadioButton aRadioButton = new JRadioButton(new DiamondIcon(Color.CYAN, false), 
true); 

aRadioButton.setSelectedIcon(new DiamondIcon(Color.BLUE, true)); 


public JRadioButton(String text) 
JRadioButton aRadioButton = new JRadioButton("4 slices"); 


public JRadioButton(String text, boolean selected) 
JRadioButton aRadioButton = new JRadioButton("8 slices", true); 


public JRadioButton(String text, Icon icon) 
JRadioButton aRadioButton = new JRadioButton("12 slices", 

new DiamondIcon(Color.CYAN, false)); 
aRadioButton.setSelectedIcon(new DiamondIcon(Color.BLUE, true)); 


public JRadioButton(String text, Icon icon, boolean selected) 
JRadioButton aRadioButton = new JRadioButton("16 slices", 

new DiamondIcon(Color.CYAN, false), true); 
aRadioButton.setSelectedIcon(new DiamondIcon(Color.BLUE, true)); 
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public JRadioButton(Action action) 
Action action = ...; 
JRadioButton aRadioButton = new JRadioButton(action); 


Note As with a JCheckBox, configuring a JRadioButton from an Action sets the label, state, and 
tooltip text, but not the icon. 


Each allows you to customize one or more of the label, icon, or initial selection state prop- 
erties. Unless specified otherwise, there's no text in the label, and the default selected /unselected 
icon for the check box appears unselected. After creating a group of radio button components, 
you need to place each into a single ButtonGroup so that they work as expected, with only 
one button in the group selectable at a time. Ifyou do initialize the icon in the constructor, 
it's the icon for the unselected state of the check box, with the same icon displayed when 
the check box is selected. You must also either initialize the selected icon with the 
setSelectedIcon(Icon newValue) method, described with JCheckBox, or make sure the icon 
is state-aware and updates itself. 


JRadioButton Properties 


JRadioButton has two properties that override the behavior ofits parent JToggleButton, as 
listed in Table 5-5. 


Table 5-5. JRadioButton Properties 


Property Name Data Type Access 
accessibleContext AccessibleContext Read-only 
UlClassID String Read-only 


Grouping JRadioButton Components in a ButtonGroup 


The JRadioButton is the only JToggleButton subclass that should be placed in a ButtonGroup 
in order to work properly. Merely creating a bunch of radio buttons and placing them on the 
screen isn't enough to make them behave appropriately. In addition to adding each radio 
button to a container, you need to create a ButtonGroup and add each radio button to the same 
ButtonGroup. Once all the JRadioButton items are in a group, whenever an unselected radio 
button is selected, the ButtonGroup causes the currently selected radio button to be deselected. 

Placing a set of JRadioButton components within a ButtonGroup on the screen is basically 
a four-step process: 


1. Create a container for the group. 


JPanel aPanel = new JPanel(new GridLayout(0, 1)); 
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Note The Box class described in Chapter 11 serves as a good container for a group of JRadioButton 
components. 


2. Place a border around the container, to label the grouping. This is an optional step, but 
you'll frequently want to add a border to label the group for the user. You can read more 
about borders in Chapter 7. 


Border border = BorderFactory.createTitledBorder("Slice Count"); 
aPanel.setBorder(border); 


3. Create a ButtonGroup. 
ButtonGroup aGroup = new ButtonGroup(); 


4. For each selectable option, create a JRadioButton, add itto a container, and then add it 
to the group. 


JRadioButton aRadioButton = new JRadioButton(...); 
aPanel.add(aRadioButton); 
aGroup.add(aRadioButton); 


You might find the whole process, especially the fourth step, a bit tedious after a while, 
especially when you add another step for handling selection events. The helper class shown 
in Listing 5-5, with its static createRadioButtonGrouping(String elements[], String title) 
method, could prove useful. It takes a String array for the radio button labels as well as the 
border title, and then it creates a set of JRadioButton objects with a common ButtonGroup in a 
JPanel with a titled border. 


Listing 5-5. Initial Support Class for Working with JRadioButton 


import javax.swing.*; 
import javax.swing.border.*; 
import java.awt.*; 


public class RadioButtonUtils ( 
private RadioButtonUtils() ( 
// Private constructor so you can't create instances 
y 
public static Container createRadioButtonGrouping (String elements[], 
String title) ( 
JPanel panel = new JPanel(new GridLayout(0, 1)); 
// 1f title set, create titled border 
if (title != null) £ 
Border border = BorderFactory.createTitledBorder(title); 
panel.setBorder(border); 


J 


137 


138 CHAPTER 5 TOGGLE BUTTONS 


// Create group 
ButtonGroup group = new ButtonGroup(); 
JRadioButton aRadioButton; 
// For each String passed in: 
// Create button, add to panel, and add to group 
for (int i=0, n=elements.length; i<n; i++) ( 
aRadioButton = new JRadioButton(elements[i]); 
panel.add(aRadioButton); 
group .add(aRadioButton); 
A 
return panel; 
J 
e 


Now, you can create the grouping much more easily, as with the sample program in 
Listing 5-6. 


Listing 5-6. Sampling JRadioButton 


import javax.swing.*; 
import java.awt.*; 


public class GroupRadio ( 
private static final String slice0ptions[] = 
("4 slices", "8 slices", "12 slices", "16 slices"); 
private static final String crustOptions[] = 
("Sicilian", "Thin Crust", "Thick Crust", "Stuffed Crust"); 
public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("Grouping Example"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
Container sliceContainer = 
RadioButtonUtils.createRadioButtonGrouping( 
sliceOptions, "Slice Count"); 
Container crustContainer = 
RadioButtonUtils.createRadioButtonGrouping( 
crustOptions, "Crust Type"); 
frame.add(sliceContainer, BorderLayout.WEST); 
frame.add(crustContainer, BorderLayout.EAST); 
frame.setSize(300, 200); 
frame.setVisible(true); 
) 
E 
EventQueue.invokeLater(runner); 
) 
) 
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When you run this example, you'll see the screen shown in Figure 5-11. 


AE 
Slice Count Crust Type 
O 4 slices O Sicilian 
O 8 slices (8) Thin Crust 
(8) 12 slices (O Thick Crust 
O 16 slices O Stuffed Crust 


Figure 5-11. Grouping JRadioButton components with the RadioButtonUtils helper class 


Note If you're familiar with the standard AWT library, the JRadioButton/ButtonGroup combination 
works exactly like the Checkbox/CheckboxGroup pair. 


Handling JRadioButton Selection Events 


Like JToggleButton and JCheckBox, JRadioButton supports the registration ofan ActionListener, 
an ItemListener, and a ChangeListener. And again, their usage with JRadioButton is somewhat 
different than with the other components. 


Listening to JRadioButton Events with an ActionListener 


With a JRadioButton, it's common to attach the same ActionListener to all the radio buttons in 
a ButtonGroup. That way, when one of the radio buttons is selected, the subscribed ActionListener 
will be notified. By overloading the earlier createRadioButtonGrouping() method, the method 
can accept an ActionListener argument and attach the listener object to each ofthe buttons as 
they're created. 


public static Container createRadioButtonGrouping (String elements[], String title, 

ActionListener actionListener) ( 

JPanel panel = new JPanel(new GridLayout(0, 1)); 

// Tf title set, create titled border 

if (title != null) € 
Border border = BorderFactory.createTitledBorder(title); 
panel.setBorder(border); 

) 

// Create group 

ButtonGroup group = new ButtonGroup(); 

JRadioButton aRadioButton; 

// For each String passed in: 

// Create button, add to panel, and add to group 
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for (int i=0, n=elements.length; i<n; i++) [ 
aRadioButton = new JRadioButton (elements[i]); 
panel.add(aRadioButton); 
group.add(aRadioButton); 
if (actionlistener != null) £ 

aRadioButton.addActionListener(actionListener); 

) 

) 


return panel; 


J 


Nowifa group is created with the following source, the same ActionListener will be notified 
for each ofthe JRadioButton components created. Here, the listener prints out only the currently 
selected value. How you choose to respond may vary. 


ActionListener sliceActionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) f 
AbstractButton aButton = (AbstractButton)actionEvent.getSource(); 
System.out.println("Selected: " + aButton.getText()); 
) 
E 
Container sliceContainer = 
RadioButtonUtils.createRadioButtonGrouping(slice0ptions, "Slice Count", 
sliceActionListener); 


However, note that there are two problems with this approach. First, if a JRadioButton is 
already selected and then selected again, any attached ActionListener objects will still be notified 
once more. Although you cannot stop the double notification of subscribed ActionListener 
objects, with a little work, you can handle it properly. You need to retain a reference to the last 
selected item and check for reselection. The following modified ActionListener checks for this: 


ActionListener crustActionListener = new ActionListener() ( 
String lastSelected; 
public void actionPerformed(ActionEvent actionEvent) ( 
AbstractButton aButton = (AbstractButton)actionEvent.getSource(); 
String label = aButton.getText(); 
String msgStart; 
if (label.equals(lastSelected)) ( 
msgStart = "Reselected: "; 
+ else [ 
msgStart = "Selected: "; 
J 
lastSelected = label; 
System.out.println(msgStart + label); 
y 
E 


The second problem has to do with determining which JRadioButton is selected at any 
given time. With the overloaded RadioButtonUtils.createRadioButtonGrouping() helper methods, 
neither the ButtonGroup nor the individual JRadioButton components are visible outside the 
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method. As a result, there's no direct route to find out which JRadioButton object (or objects) is 
selected within the ButtonGroup of the returned container. This may be necessary, for example, 
ifthere were an Order Pizza button on the screen and you wanted to find out which pizza-order 
options were selected after the user clicked that button. 

The following helper method, public Enumeration getSelectedElements (Container 
container), when added to the previously created RadioButtonUtils class (Listing 5-5), will 
provide the necessary answer. The helper method will work only ifthe container passed into 
the method is full of AbstractButton objects. This is true for those containers created with the 
previously described createRadioButtonGrouping() methods, although the getSelectedElements () 
method can be used separately. 


public static Enumeration<String> getSelectedElements(Container container) ( 
Vector<String> selections = new Vector<String>»(); 
Component components[] = container.getComponents(); 
for (int i=0, n=components.length; i<n; i++) ( 
if (components[i] instanceof AbstractButton) Y 
AbstractButton button = (AbstractButton)components[i]; 
if (button.isSelected()) f 
selections.addElement(button.getText()); 
) 
) 
y 


return selections.elements(); 


) 


To use the getSelectedElements() method, you just need to pass the container returned 
from createRadioButtonGrouping() to the getSelectedElements() method to get an Enumeration of 
the selected items as String objects. The following example demonstrates this. 


final Container crustContainer = 
RadioButtonUtils.createRadioButtonGrouping(crustOptions, "Crust Type"); 


ActionListener buttonActionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
Enumeration selected = RadioButtonUtils.getSelectedElements (crustContainer); 
while (selected.hasMoreElements()) f 
System.out.println ("Selected -> " 
) 
) 
E 
JButton button = new JButton ("Order Pizza"); 
button.addActionListener(buttonActionListener); 


+ selected.nextElement()); 


It may be necessary for getSelectedElements() to return more than one value, because if 
the same ButtonModel is shared by multiple buttons in the container, multiple components ofthe 
ButtonGroup will be selected. Sharing a ButtonModel between components isn't the norm. If 
you're sure your button model won't be shared, then you may want to provide a similar 
method that returns only a String. 
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Listening to JRadioButton Events with an ItemListener 


Depending on what you're trying to do, using an ItemlL istener with a JRadioButton is usually 
not the desired event-listening approach. When an ItemListener is registered, a new JRadioButton 
selection notifies the listener twice: once for deselecting the old value and once for selecting 
the new value. For reselections (selecting the same choice again), the listener is notified only once. 

To demonstrate, the following listener will detect reselections, as the ActionListener did 
earlier, and will report the selected (or deselected) element. 


ItemListener itemListener = new ItemListener() f 

String lastSelected; 

public void itemStateChanged(ItemEvent itemEvent) ( 
AbstractButton aButton = (AbstractButton)itemEvent.getSource(); 
int state = itemEvent.getStateChange(); 
String label = aButton.getText(); 
String msgStart; 
if (state == ItemEvent.SELECTED) f 

if (label.equals(lastSelected)) ( 


" 


msgStart = "Reselected -> "; 


y else f 
msgStart = "Selected -> "; 
) 
lastSelected = label; 
+ else f 
msgStart = "Deselected -> "; 
) 
System.out.println(msgStart + label); 
) 
$» 


To work properly, some new methods will be needed for RadioButtonUtils to enable you 
to attach the ItemListener to each JRadioButton in the ButtonGroup. They're listed in the 
following section with the source for the complete example. 


Listening to JRadioButton Events with a ChangeListener 


The ChangeListener responds to the JRadioButton just as it does with the JToggleButton and 
JCheckBox. A subscribed listener is notified when the selected radio button is armed, pressed, 
selected, or released and for various other properties ofthe button model. The only difference 
with JRadioButton is that the ChangeListener is also notified of the state changes of the radio 
button being deselected. The ChangeListener from the earlier examples could be attached to 
the JRadioButton as well. It will just be notified more frequently. 

The sample program shown in Listing 5-7 demonstrates all the listeners registered to the 
events of two different JRadioButton objects. In addition, a JButton reports on the selected 
elements of one of the radio buttons. Figure 5-12 shows the main window of the program. 
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Listing 5-7. Radio Button Group Sample 


import javax.swing.*; 

import javax.swing.event.*; 
import java.awt.*; 

import java.awt.event.*; 
import java.util.Enumeration; 


public class GroupActionRadio ( 
private static final String slice0ptions[] = 
("4 slices", "8 slices", "12 slices", "16 slices"p; 
private static final String crustOptions[] = 
("Sicilian", "Thin Crust", "Thick Crust", "Stuffed Crust"); 
public static void main(String args[]) ( 
Runnable runner = new Runnable() 4 
public void run() £ 
JFrame frame = new JFrame("Grouping Example"); 
frame.setDefaultClose0peration(JFrame.EXIT_ON CLOSE); 


// Slice Parts 
ActionListener sliceActionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
AbstractButton aButton = (AbstractButton)actionEvent.getSource(); 
System.out.println("Selected: " + aButton.getText()); 
) 
E 
Container sliceContainer = 
RadioButtonUtils.createRadioButtonGrouping(sliceOptions, 
"Slice Count", sliceActionListener); 


// Crust Parts 
ActionListener crustActionListener = new ActionListener() ( 
String lastSelected; 
public void actionPerformed(ActionEvent actionEvent) ( 
AbstractButton aButton = (AbstractButton)actionEvent.getSource(); 
String label = aButton.getText(); 
String msgStart; 
if (label.equals(lastSelected)) ( 
msgStart = "Reselected: "; 
) else £ 
msgStart = "Selected: "; 
) 
lastSelected = label; 
System.out.println(msgStart + label); 


E; 
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ItemListener itemlListener = new ItemListener() f 

String lastSelected; 

public void itemStateChanged(ItemEvent itemEvent) ( 
AbstractButton aButton = (AbstractButton)itemEvent.getSource(); 
int state = itemEvent.getStateChange(); 
String label = aButton.getText(); 
String msgStart; 
if (state == ItemEvent.SELECTED) 4 

if (label.equals(lastSelected)) ( 


" 


msgStart = "Reselected -> "; 


j else £ 
msgStart = "Selected -> "; 
y 
lastSelected = label; 
y else [ 
msgStart = "Deselected -> "; 
J 
System.out.println(msgStart + label); 


h 
5 
Changelistener changeListener = new Changelistener() ( 
public void stateChanged(ChangeEvent changEvent) ( 
AbstractButton aButton = (AbstractButton)changEvent.getSource(); 
ButtonModel aModel = aButton.getModel (>; 
boolean armed = aModel.isArmed(); 
boolean pressed = aModel.isPressed(); 
boolean selected = aModel.isSelected(); 
System.out.println("Changed: " + armed + "/" + pressed + "/" + 
selected); 
) 
E 
final Container crustContainer = 
RadioButtonUtils.createRadioButtonGrouping(crustOptions, 
"Crust Type", crustActionListener, itemListener, changeListener); 


// Button Parts 
ActionListener buttonActionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
Enumeration<String> selected = 
RadioButtonUtils.getSelectedElements(crustContainer); 
while (selected.hasMoreElements()) f 
System.out.println ("Selected -> " + selected.nextElement()); 
) 
) 
E 


JButton button = new JButton ("Order Pizza"); 
button.addActionListener(buttonActionListener); 


frame 


frame 


) 
E; 


.add(sliceContainer, BorderLayout.WEST); 
frame. 
frame. 
.setSize(300, 200); 
frame. 


add(crustContainer, BorderLayout.EAST); 
add(button, BorderLayout.SOUTH); 


setVisible(true); 


EventQueue.invokeLater(runner); 


y 
J 


[2 Growpig example AA 
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(8) 4 slices 
O 8 slices 
O 12 slices 


O 16 slices 
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Order Pizza 


Figure 5-12. The GroupActionRadio program sample screen 
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A few more changes were made to the RadioButtonUtils class to deal with registering 
ChangeListener objects to all the radio buttons in a ButtonGroup. The complete and final class 
definition is shown in Listing 5-8. 


Listing 5-8. Complete Support Class for Working with JRadioButton 


pb. pe hp. pe hp. pp. pe 


port javax.swing.*; 

port javax.swing.event.*; 
port javax.swing.border.*; 
port java.awt.*; 

port java.awt.event.*; 

port java.util.Enumeration; 
port java.util.Vector; 


public class RadioButtonUtils ( 
private RadioButtonUtils() ( 


// Private constructor so you can't create 


J 


instances 
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public static Enumeration<String> getSelectedElements(Container container) ( 
Vector<String> selections = new Vector<String>(); 
Component components[] = container.getComponents(); 
for (int i=0, n=components.length; i<n; i++) ( 
if (components[i] instanceof AbstractButton) ( 
AbstractButton button = (AbstractButton)components[i]; 
if (button.isSelected()) f 
selections.addElement (button.getText()); 
J 
) 
) 


return selections.elements(); 


J 


public static Container createRadioButtonGrouping (String elements[]) ( 
return createRadioButtonGrouping(elements, null, null, null, null); 


y 


public static Container createRadioButtonGrouping (String elements[], 
String title) ( 
return createRadioButtonGrouping(elements, title, null, null, null); 


J 


public static Container createRadioButtonGrouping(String elements[], 
String title, ItemListener itemListener) ( 
return createRadioButtonGrouping(elements, title, null, itemListener, null); 


J 


public static Container createRadioButtonGrouping(String elements[], 
String title, ActionlListener actionListener) ( 
return createRadioButtonGrouping(elements, title, actionListener, null, 
null); 


J 


public static Container createRadioButtonGrouping(String elements[], 
String title, Actionlistener actionListener, ItemListener itemListener) ( 
return createRadioButtonGrouping(elements, title, actionListener, 
itemListener, null); 


J 


public static Container createRadioButtonGrouping(String elements[], 
String title, ActionListener actionlListener, ItemlListener itemListener, 
ChangelListener changeListener) ( 
JPanel panel = new JPanel(new GridLayout(0, 1)); 
// Tf title set, create titled border 
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if (title != null) £ 
Border border = BorderFactory.createTitledBorder(title); 
panel.setBorder(border); 
y 
// Create group 
ButtonGroup group = new ButtonGroup(); 
JRadioButton aRadioButton; 
// For each String passed in: 
// Create button, add to panel, and add to group 
for (int i=0, n=elements.length; i<n; i++) [ 
aRadioButton = new JRadioButton (elements[i]); 
panel.add(aRadioButton); 
group .add(aRadioButton); 
if (actionlistener != null) £ 
aRadioButton.addActionListener(actionListener); 
J 
if (itemListener != null) ( 
aRadioButton.addItemListener(itemListener); 
) 
if (changelistener != null) ( 
aRadioButton.addChangeListener(changeListener); 
J 
h 
return panel; 
) 
J 


Note One thing not shown here but explained in Chapter 4 in the discussion of ButtonModel and 
DefaultButtonModel is how to get the ButtonGroup when given a JRadioButton. If you want to find 
the ButtonGroup that a JRadioButton is in, you need to ask the DefaultButtonModel: ButtonGroup 
group = ((DefaultButtonModel)aJRadioButton.getModel()).getButtonGroup(). 


Customizing a JRadioButton Look and Feel 


Each installable Swing look and feel provides a different JRadioButton appearance and set of 
default UTResource values. Figure 5-13 shows the appearance of the JRadioButton component 
for the preinstalled set of look and feel types: Motif, Windows, and Ocean. All three screens 
show 4 slices of Thin Crust pizza as the order. In addition, the Thick Crust option has the input 
focus. 
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Figure 5-13. JRadioButton under different look and feel types 


Table 5-6 shows the set of available UIResource-related properties for a JRadioButton. 
The JRadioButton component has 20 different properties available. 


Table 5-6. JRadioButton UlResource Elements 


Property String Object Type 
RadioButton.background Color 
RadioButton.border Border 
RadioButton.darkShadow Color 
RadioButton.disabledText Color 
RadioButton.focus Color 
RadioButton.FfocusInputMap Object[ ] 
RadioButton. font Font 
RadioButton.foreground Color 
RadioButton.gradient List 
RadioButton.highlight Color 
RadioButton.icon Icon 
RadioButton.interiorBackground Color 
RadioButton. light Color 


RadioButton.margin Insets 
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Table 5-6. JRadioButton UlResource Elements (Continued) 


Property String Object Type 
RadioButton.rollover Boolean 
RadioButton.select Color 
RadioButton.shadow Color 
RadioButton.textIconGap Integer 
RadioButton.textShiftOffset Integer 
RadioButtonUI String 


Summary 


This chapter described the components that can be toggled: JToggleButton, JCheckBox, and 
JRadioButton. You've seen how each component uses the JToggleButton. ToggleButtonModel 
class for its data model and how you can group the components into a ButtonGroup. In addition, 
you also saw how to handle selection events for each of the components. 

Chapter 6 explains how to work with the various menu-oriented Swing components. 
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Swing Menus and Toolbars 


M any of the low-level Swing components were covered in the previous two chapters of this 
book. This chapter will delve into Swing's menu-related components. Menus and toolbars help 
make your applications more user-friendly by providing visual command options. Users can 
avoid the somewhat archaic multiple-key command sequences that are holdovers from programs 
such as the early word processor WordStar and the more current emacs programmer's editor. 
Although Swing menus do support multiple-key command sequences, the menus (and toolbars) 
are designed primarily for on-screen graphical selection with a mouse, rather than the keyboard. 
The menu components discussed in this chapter are used as follows: 


+ For each cascading menu, you create a Menu component and add it to the JMenuBar. 


+ For the selections available from the JMenu, you create JMenuItem components and add 
them to the JMenu. 


+ To create submenus, you add a new JMenu to a JMenu and place JMenulItem options on the 
new menu. 


+ Then, when a JMenu is selected, the system displays its current set of components within 
a JPopupMenu. 


In addition to the basic JMenuTtem elements, this chapter covers other menu items, such as 
JCheckBoxMenultem and JRadioButtonMenultem, which you can place within a JMenu. You'll also 
explore the JSeparator class, which serves to divide menu items into logical groups. You'll find 
out how to use the JPopupMenu class for general support of pop-up menus that appear after a 
JMenu is selected, or in context for any component. As with abstract buttons (the AbstractButton 
class was introduced in Chapter 4), each menu element can have a mnemonic associated with 
it for keyboard selection. You'll also learn about the support for keyboard accelerators, which 
allow users to avoid going through all the menuing levels for selection. 

Besides the individual menu-related components, in this chapter you'll look at the JMenuBar 
selection model and event-related classes specific to menus. The selection model interface 
to examine is the SingleSelectionModel interface, as well as its default implementation 
DefaultSingleSelectionModel. You'll explore the menu-specific listeners and events 
MenuListener/MenuEvent, MenuKeyListener/MenuKeyEvent, and MenuDragMousel istener/ 
MenuDragMouseEvent. In addition, you'll examine creating other pop-up components with 
Popup and PopupFactory, as well as using toolbars with the JToo1Bar class. 
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Working with Menus 


Let's begin with an example that demonstrates how all the menu components fit together. 
To start, create a frame with a menu bar, as shown in Figure 6-1. 


Accelerator 


Mnemonic 


- (0) xj 
JMenuBar 


JMenultem TI Find 
, z o E 1 
3) Options CIA E RadioButtonMenultem 


Backward 


aan (ET JSeparator 
Case Sensitive_ «————— JCheckBoxMenultem 


JPopupMenu 


Figure 6-1. Menu component examples 


This simple menuing example has the following features: 


On the menu bar are two ubiquitous menus: File and Edit. Under the File menu, the 
familiar options of New, Open, Close, and Exit will appear (although they aren't shown 
in Figure 6-1). Under the Edit menu are options for Cut, Copy, Paste, and Find, and a 
submenu of Find options. The Options submenu will contain choices for search direction— 
forward or backward—and a toggle for case sensitivity. 


In various places within the different menus, menu separators divide the options into 
logical sets. 


Each of the menu options has a mnemonic associated with it to help with keyboard 
navigation and selection. The mnemonic allows users to make menu selections via the 
keyboard, for instance, by pressing Alt-F on a Windows platform to open the File menu. 


In addition to the keyboard mnemonic, a keystroke associated with several options acts 
as a keyboard accelerator. Unlike the mnemonic, the accelerator can directly activate a 
menu option, even when the menu option isn't visible. 


The Options submenu has anicon associated with it. Although only one icon is shown in 
Figure 6-1, all menu components can have an icon, except for the JSeparator and 
JPopupMenu components. 
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Note that for this beginning example, none of the menu choices will do anything other 
than print which menu choice was selected. For example, selecting the Copy option from the 
Edit menu displays Selected: Copy. 

Listing 6-1 shows the complete source for the class that generated the example in Figure 6-1. 


Listing 6-1. The MenuSample Class Definition 


import java.awt.*; 
import java.awt.event.*; 
import javax.swing.*; 


public class MenuSample ( 
static class MenuActionListener implements ActionListener ( 
public void actionPerformed (ActionEvent actionEvent) ( 
System.out.println ("Selected: " + actionEvent.getActionCommand()); 
4 


) 
public static void main(final String args[]) ( 


Runnable runner = new Runnable() 4 
public void run() £ 
ActionListener menuListener = new MenuActionListener(); 
JFrame frame = new JFrame("MenuSample Example"); 
frame.setDefaultClose0peration(JFrame.EXIT_ON CLOSE); 
JMenuBar menuBar = new JMenuBar(); 


// File Menu, F - Mnemonic 

JMenu fileMenu = new JMenu("File"); 
fileMenu.setMnemonic(KeyEvent.VK_F); 
menuBar .add(fileMenu) ; 


// File->New, N - Mnemonic 

JMenuTtem nenMenultem = new JMenultem("New", KeyEvent.VK_N); 
newMenultem. addActionListener(menuListener); 
fileMenu.add(newMenultem) ; 


// File->0pen, O - Mnemonic 

JMenuTtem openMenultem = new JMenultem("Open", KeyEvent.VK_0); 
openMenuTtem.addActionListener(menuListener); 
fileMenu.add(openMenultem); 


// File->Close, C - Mnemonic 

JMenuTtem closeMenultem = new JMenultem("Close", KeyEvent.VK_C); 
closeMenultem. addActionListener(menuListener); 
fileMenu.add(closeMenultem) ; 
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// Separator 
fileMenu.addSeparator(); 


// File->Save, S - Mnemonic 

JMenultem saveMenultem = new JMenultem("Save", KeyEvent.VK_S); 
saveMenultem.addActionListener(menuListener); 
fileMenu.add(saveMenultem) ; 


// Separator 
fileMenu.addSeparator(); 


// File->Exit, X - Mnemonic 

JMenultem exitMenultem = new JMenultem("Exit", KeyEvent.VK_X); 
exitMenultem.addActionListener(menuListener); 
fileMenu.add(exitMenultem) ; 


// Edit Menu, E - Mnemonic 

JMenu editMenu = new JMenu("Edit"); 
editMenu.setMnemonic(KeyEvent.VK_E); 
menuBar.add(editMenu); 


// Edit->Cut, T - Mnemonic, CTRL-X - Accelerator 

JMenultem cutMenultem = new JMenultem("Cut", KeyEvent.VK_T); 
cutMenultem.addActionListener(menuListener); 

KeyStroke ctrlXKeyStroke = KeyStroke.getKeyStroke("control X"); 
cutMenultem.setAccelerator(ctrlXKeyStroke); 
editMenu.add(cutMenultem); 


// Edit->Copy, C - Mnemonic, CTRL-C - Accelerator 

JMenultem copyMenultem = new JMenultem("Copy", KeyEvent.VK_C); 
copyMenultem.addActionListener(menuListener); 

KeyStroke ctrlCKeyStroke = KeyStroke.getKeyStroke("control C"); 
copyMenultem. setAccelerator(ctrlCKeyStroke); 
editMenu.add(copyMenuItem); 


// Edit->Paste, P - Mnemonic, CTRL-V - Accelerator, Disabled 
JMenultem pasteMenultem = new JMenultem("Paste", KeyEvent.VK_P); 
pasteMenultem.addActionListener(menuListener); 

KeyStroke ctrlVKeyStroke = KeyStroke.getKeyStroke("control V"); 
pasteMenultem.setAccelerator(ctrlWKeyStroke); 
pasteMenultem.setEnabled(false); 

editMenu.add(pasteMenultem); 


// Separator 
editMenu.addSeparator(); 
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// Edit->Find, F - Mnemonic, F3 - Accelerator 

JMenuTtem findMenultem = new JMenultem("Find", KeyEvent.VK_F); 
findMenultem.addActionListener(menuListener); 

KeyStroke f3KeyStroke = KeyStroke.getKeyStroke("F3"); 
findMenultem.setAccelerator(f3KeyStroke); 
editMenu.add(findMenultem); 


// Edit->Options Submenu, O - Mnemonic, at.gif - Icon Image File 
JMenu findOptionsMenu = new JMenu("Options”); 

Icon atlcon = new Imagelcon ("at.gif"); 
findO0ptionsMenu.setIcon(atIcon); 
findO0ptionsMenu.setMnemonic(KeyEvent.VK_0); 


// ButtonGroup for radio buttons 
ButtonGroup directionGroup = new ButtonGroup(); 


// Edit->Options->Forward, F - Mnemonic, in group 
JRadioButtonMenultem forwardMenultem = 

new JRadioButtonMenultem("Forward", true); 
forwardMenulItem.addActionListener(menuListener); 
forwardMenultem.setMnemonic(KeyEvent.VK_F); 
findO0ptionsMenu.add(forwardMenultem); 
directionGroup.add(forwardMenulItem); 


// Edit->Options->Backward, B - Mnemonic, in group 
JRadioButtonMenultem backwardMenultem = 

new JRadioButtonMenultem("Backward"); 
backwardMenulItem.addActionListener(menuListener); 
backwardMenuItem. setMnemonic(KeyEvent.VK_B); 
findO0ptionsMenu.add(backwardMenuItem); 
directionGroup.add(backwardMenuItem); 


// Separator 
findO0ptionsMenu.addSeparator(); 


// Edit->Options->Case Sensitive, C - Mnemonic 
JCheckBoxMenultem caseMenultem = 

new JCheckBoxMenultem("Case Sensitive"); 
caseMenultem.addActionListener(menuListener); 
caseMenultem.setMnemonic(KeyEvent.VK_C); 
findO0ptionsMenu.add(caseMenultem); 
editMenu.add(FindOptionsMenu); 
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frame.setJMenuBar (menuBar) ; 
frame.setSize(350, 250); 
frame.setVisible(true); 
y 
E 
EventQueue.invokeLater(runner); 
J 
y 


Menu Class Hierarchy 


Now that you've seen an example of howto create the cascading menus for an application, you 
should have an idea of what's involved in using the Swing menu components. To help clarify, 
Figure 6-2 illustrates how all the Swing menu components are interrelated. 


> 
JComponent 
JMenuBar JPopupMenu JSeparator AbstractButton 
SCI EI 
A era a JMenuTtem 
NN 
JMenu cm | JRadioButtonMenultem 


Figure 6-2. Swing menu class hierarchy 


The most important concept illustrated in Figure 6-2 is that all the Swing menu elements, 
as subclasses of JComponent, are AWT components in their own right. You can place JMenulten, 
JMenu, and JMenuBar components anywhere that AWT components can go, not just on a frame. 
In addition, because JMenulItem inherits from AbstractButton, JMenultem and its subclasses 
inherit support for various icons and for HTML text labels, as described in Chapter 5. 
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Note Although technically possible, placing menus in locations where users wouldn't expect them to be 
is poor user interface design. 


In addition to being part of the basic class hierarchy, each of the selectable menu components 
implements the MenuElement interface. The interface describes the menu behavior necessary to 
support keyboard and mouse navigation. The predefined menu components already imple- 
ment this behavior, so you don't have to. But if you're interested in how this interface works, 
see the “MenuElement Interface” section later in this chapter. 

Now let's take a look at the different Swing menu components. 


JMenuBar Class 


Swing's menu bar component is the JMenuBar. Its operation requires you to fill the menu bar 
with JMenu elements that have JMenuTtem elements. Then you add the menu bar to a JFrame or 
some other user interface component requiring a menu bar. The menu bar then relies on the 
assistance ofa SingleSelectionModel to determine which JMenu to display or post after it's selected. 


Creating JMenuBar Components 


JMenuBar has a single constructor of the no-argument variety: public JMenuBar(). Once you 
create the menu bar, you can add it to a window with the setJMenuBar() method of JApplet, 
JDialog, JFrame, JInternalFrame, or JRootPane. (Yes, even applets can have menu bars.) 


JMenuBar menuBar = new JMenuBar(); 
// Add items to it 


JFrame frame = new JFrame("MenuSample Example"); 
frame .setJMenuBar (menuBar) ; 


With the system-provided look and feel types, the menu bar appears at the top ofthe 
window, below any window title (if present), with setJMenuBar (). Other look and feel types, like 
Aqua for the Macintosh, place the menu bar elsewhere. 

You can also use the add() method of a Container to add a JMenuBar to a window. When 
added with the add() method, a JMenuBar is arranged by the layout manager of the Container. 

After you have a JMenuBar, the remaining menu classes all work together to fill the menu bar. 


Adding Menus to and Removing Menus from Menu Bars 


You need to add JMenu objects to a JMenuBar. Otherwise, the only thing displayed is the border 
with nothing in it. There's a single method for adding menus to a JMenuBar: 


public JMenu add(JMenu menu) 
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By default, consecutively added menus are displayed from left to right. This makes the first 
menu added the leftmost menu and the last menu added the rightmost menu. Menus added in 
between are displayed in the order in which they're added. For instance, in the sample program 
from Listing 6-1, the menus were added as follows: 


JMenu fileMenu = new JMenu("File"); 
menuBar.add(fileMenu) ; 
JMenu editMenu = new JMenu("Edit"); 
menuBar.add(editMenu) ; 


Note Placing a JMenuBar in the EAST or WEST area of a BorderLayout does not make the menus 
appear vertically, stacked one on top of another. You must customize the menu bar if you want menus to 
appear this way. See Figure 6-4, later in this chapter, for one implementation of a top-down menu bar. 


In addition to the add() method from JMenuBar, several overloaded varieties of the add() 
method inherited from Container offer more control over menu positioning. Of particular 
interest is the add(Component component, int index) method, which allows you to specify the 
position in which the new JMenu is to appear. Using this second variety of add() allows you to 
place the File and Edit JMenu components in a JMenuBar in a different order, but with the 
same results: 


menuBar .add(editMenu) ; 
menuBar.add(fileMenu, 0); 


If you've added a JMenu component to a JMenuBar, you can remove it with either the 
remove (Component component) or remove(int index) method inherited from Container: 


bar.remove(edit); 
bar.remove(0); 


Tip Adding or removing menus from a menu bar ¡s likely to confuse users. However, sometimes it's necessary 
to do so—especially if you want to have an expert mode that enables a certain functionality that a nonexpert 
mode hides. A better approach is to disable/enable individual menu items or entire menus. If you do add or 
remove menus, you must then revalidate() the menu bar to display the changes. 


JMenuBar Properties 


Table 6-1 shows the 11 properties of JMenuBar. Half the properties are read-only, allowing you 
only to query the current state of the menu bar. The remaining properties allow you to alter the 
appearance of the menu bar by deciding whether the border of the menu bar is painted and 
selecting the size ofthe margin between menu elements. The selected property and selection 
model control which menu on the menu bar, if any, is currently selected. When the selected 
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component is set to a menu on the menu bar, the menu components appear in a pop-up menu 
within a window. 


Caution The helpMenu property, although available with a set-and-get method, is unsupported in the 
Swing releases through 5.0. Calling either accessor method will throw an error. With some future release of 
Swing, the he1pMenu property will likely make a specific JMenu the designated help menu. Exactly what 
happens when a menu is flagged as the help menu ¡is specific to the installed look and feel. What tends to 
happen is that the menu becomes the last, or rightmost, menu. 


Table 6-1. JMenuBar Properties 


Property Name Data Type Access 

accessibleContext AccessibleContext Read-only 
borderPainted boolean Read-write 
component Component Read-only 
helpMenu JMenu Read-write 
margin Insets Read-write 
menuCount int Read-only 
selected boolean/Component Read-write 
selectionModel SingleSelectionModel Read-write 
subElements MenuElement[ ] Read-only 
UI MenuBarul Read-write 
UlClassID String Read-only 


Note The selected property of JMenuBar is nonstandard. The getter method returns a boolean to 
indicate if a menu component is selected on the menu bar. The setter method accepts a Component argument 
to select a component on the menu bar. 


Customizing a JMenuBar Look and Feel 


Each predefined Swing look and feel provides a different appearance and set of default UTResource 
values for the JMenuBar and each of the menu components. Figure 6-3 shows the appearance 
of all these menu components for the preinstalled set of look and feel types: Motif, Windows, 
and Ocean. 
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Figure 6-3. Menu components under different look and feel types 


In regard to the specific appearance of the JMenuBar, the available set of UIResource-related 
properties is shown in Table 6-2. There are 12 properties available for the JMenuBar component. 


Table 6-2. JMenuBar UlResource Elements 


Property String Object Type 
MenuBar.actionMap ActionMap 
MenuBar .background Color 
MenuBar .border Border 
MenuBar .borderColor Color 
MenuBar.darkShadow Color 
MenuBar. font Font 
MenuBar.foreground Color 
MenuBar.gradient List 
MenuBar.highlight Color 
MenuBar . shadow Color 
MenuBar .windowBindings Object[ ] 


MenuBarUl String 
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Ifyou want a vertical menu bar, instead of a horizontal one, simply change the LayoutManager 
of the menu bar component. A setup such as a O row by 1 column GridLayout does the job, as 
shown in the following example, because the number of rows will grow infinitely for each JMenu 
added: 


import java.awt.*; 
import javax.swing.*; 
public class VerticalMenuBar extends JMenuBar £ 
private static final LayoutManager grid = new Gridlayout(0,1); 
public VerticalMenuBar() ( 
setLayout(grid); 
y 
J 


Moving the menu bar shown in Figure 6-1 to the east side of a BorderLayout and making it 
a VerticalMenuBar instead of a JMenuBar produces the setup shown in Figure 6-4. Although the 
vertical menu bar may look a little unconventional here, it's more desirable to have menu items 
appearing stacked vertically, rather than horizontally, on the right (or left) side of a window. You 
may, however, want to change the MenuBar. border property to a more appropriate border. 


ercer A 


Figure 6-4. Using the VerticalMenuBar 


Note Changing the layout manager of the JMenuBar has one negative side effect: Because top-level menus 
are pull-down menus, open menus on a vertical bar will obscure the menu bar. If you want to correct this pop- 
up placement behavior, you must extend the JMenu class and override its protected getPopupMenu0rigin() 
method in order to make the pop-up menu span out, rather than drop down. 


SingleSelectionModel Interface 


The SingleSelectionModel interface describes an index into an integer-indexed data structure 
where an element can be selected. The data structure behind the interface facade is most likely 
an array or vector in which repeatedly accessing the same position is guaranteed to return the 
same object. The SingleSelectionModel interface is the selection model for a JMenuBar as well 
as a JPopupMenu. In the case of a JMenuBar, the interface describes the currently selected JMenu 
that needs to be painted. In the case of a JPopupMenu, the interface describes the currently 
selected JMenuTtem. 


161 


162 CHAPTER 6 SWING MENUS AND TOOLBARS 


Note SingleSelectionModel also serves as the selection model for JTabbedPane, a class described 
in Chapter 11. 


The interface definition for SingleSelectionModel follows: 


public interface SingleSelectionModel £ 
// Listeners 
public void addChangeListener(Changelistener listener); 
public void removeChangeListener(ChangeListener listener); 
// Properties 
public int getSelectedIndex(); 
public void setSelectedIndex(int index); 
public boolean isSelected(); 
// Other Methods 
public void clearSelection(); 


As you can see, in addition to the selection index, the interface requires maintenance ofa 
ChangeListener list to be notified when the selection index changes. 

The default Swing-provided implementation of SingleSelectionModel is the 
DefaultSingleSelectionModel class. For both JMenuBar and JPopupMenu, it's very unlikely that 
you will change their selection model from this default implementation. 

The DefaultSingleSelectionModel implementation manages the list of ChangeListener 
objects. In addition, the model uses a value of —1 to signify that nothing is currently selected. 
When the selected indexis—1, issSelected() returns false; otherwise, the method returns true. 
When the selected index changes, any registered ChangeListener objects will be notified. 


JMenultem Class 


The JMenuTtem component is the predefined component that a user selects on a menu bar. Asa 
subclass of AbstractButton, JMenultem acts as a specialized button component that behaves 
similarly to a JButton. Besides being a subclass of AbstractButton, the JMenultem class shares 
the data model of JButton (ButtonModel interface and DefaultButtonModel implementation). 


Creating JMenultem Components 


Six constructors for JMenulTtem follow. They allow you to initialize the menu item's string oricon 
label and the mnemonic of the menu item. There's no explicit constructor permitting you to 
set all three options at creation time, unless you make them part of an Action. 
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public JMenuTtem() 
JMenultem jMenultem = new JMenultem(); 


public JMenultem(Icon icon) 
Icon atlcon = new Imagelcon("at.gif"); 
JMenultem jMenultem = new JMenultem(atIcon); 


public JMenultem(String text) 
JMenultem jMenultem = new JMenultem("Cut"); 


public JMenultem(String text, Icon icon) 
Icon atlcon = new Imagelcon("at.gif"); 
JMenultem jMenultem = new JMenultem("Options", atIcon); 


public JMenultem(String text, int mnemonic) 
JMenultem jMenultem = new JMenultem("Cut", KeyEvent.VK_T); 


public JMenulTtem(Action action) 
Action action = ...; 
JMenultem jMenultem = new JMenultem(action); 


The mnemonic allows you to select the menu through keyboard navigation. For instance, 
you can simply press Alt-T on a Windows platform to select the Cut menu item if the item 
appears on an Edit menu that is already open. The mnemonic for a menu item usually appears 
underlined within the text label for the menu. However, if the letter doesn't appear within the 
text label or if there is no text label, the user will have no visual clue as to its setting. Letters are 
specified by the different key constants within the java. awt.event.KeyEvent class. 

Other platforms might offer other meta-keys for selecting mnemonics. On UNIX, the 
meta-key is also an Alt key; on a Macintosh, it's the Command key. 


Note Adding a JMenultem with a label of “-” doesn't create a menu separator as it did with AWT's 
Menultem. 


JMenultem Properties 


The JMenulten class has many properties. Roughly 100 properties are inherited through its 
various superclasses. The 10 properties specific to JMenuTtem are shown in Table 6-3. 
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Table 6-3. JMenultem Properties 


Property Name Data Type Access 
accelerator KeyStroke Read-write bound 
accessibleContext AccessibleContext Read-only 

armed boolean Read-write 
component Component Read-only 
enabled boolean Write-only bound 
menuDragMouseListeners MenuDragMouseListener[ ] Read-only 
menuKeyListeners MenuKeyListener[ ] Read-only 
subElements MenuElement[ ] Read-only 

UI MenuElementUI Write-only bound 
UlClassID String Read-only 


One truly interesting property is accelerator. As explained in Chapter 2, KeyStroke is a 
factory class that lets you create instances based on key and modifier combinations. For instance, 
the following statements, from the example in Listing 6-1 earlier in this chapter, associate Ctrl-X as 
the accelerator for one particular menu item: 


KeyStroke ctrlXKeyStroke=KeyStroke.getKeyStroke("control X"); 
cutMenuTtem.setAccelerator(ctrlXKeyStroke); 


The read-only component and subElements properties are part of the MenuE lement interface, 
which JMenuTtem implements. The component property is the menu item renderer (the JMenuTtem 
itself). The subElements property is empty (that is, an empty array, not nul1), because a JMenultem 
has no children. 


Note Swing menus don't use AWT's MenuShortcut class. 


Handling JMenultem Events 


You can handle events within a JMenuTtenm in at least five different ways. The component inherits 
the ability to allow you to listen for the firing of ChangeEvent and ActionEvent through the 
ChangeListener and ActionListener registration methods of AbstractButton. In addition, the 
JMenuTtem component supports registering MenuKeyListener and MenuDragMouseListener 
objects when MenuKeyEvent and MenuDragMouseEvent events happen. These techniques are 
discussed in the following sections. A fifth way is to pass an Action to the JMenultem constructor, 
which is like a specialized way of listening with an ActionListener. For more on using Action, 
seethe discussion ofusing Action objects with menus, in the “Menu Class” section a little later 
in this chapter. 
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Listening to JMenultem Events with a ChangeListener 


Normally, you wouldn't register a ChangeListener with a JMenultem. However, demonstrating 
one hypothetical case helps to clarify the data model changes of the JMenuTtem with respect to 
its ButtonModel. The changes with regard to arming, pressing, and selecting are the same as 
with a JButton. However, their naming might be a little confusing because the selected property of 
the model is never set. 

A JMenultemis armed when the mouse passes over the menu choice and it becomes selected. 
A JMenultenmis pressed when the user releases the mouse button over it. Immediately after being 
pressed, the menu item becomes unpressed and unarmed. Between the menu item being 
pressed and unpressed, the AbstractButton is notified ofthe model changes, causing any regis- 
tered ActionListener objects ofthe menu item to be notified. The button model for a plain 
JMenuTtem never reports being selected. If you move the mouse to another menu item without 
selecting, the first menu item automatically becomes unarmed. To help you better visualize 
the different changes, Figure 6-5 shows a sequence diagram. 


ActionListener ChangeListener ActionListener 
List of List of List of ButtonModel 
JMenultem JMenultem ButtonModel 


Registers with 


Registers with 


A 
MO 


Pressed 


No Longer. Pressed 


No Longer. Armed 


Figure 6-5. JMenultem selection sequence diagram 


Note Subclasses of JMenuItem can have their button model selected property set, like a radio button— 
but the predefined JMenuTtem cannot. 


166 


CHAPTER 6 SWING MENUS AND TOOLBARS 


Listening to JMenultem Events with an ActionListener 


The better listener to attach to a JMenuTtem is the ActionListener, or passing an Action to the 
constructor. It allows you to find out when a menu item is selected. Any registered ActionListener 
objects would be notified when a user releases the mouse button over a JMenuTtem that is part 
of an open menu. Registered listeners are also notified ifthe user employs the keyboard 
(whether with arrow keys or mnemonics) or presses the menu item's keyboard accelerator to 
make a selection. 

You must add an ActionListener to every JMenuTtem for which you want an action to happen 
when selected. There's no automatic shortcut allowing you to register an ActionListener with 
a JMenu or JMenuBar and have all their contained JMenuTtem objects notify a single ActionListener. 

The sample program shown in Listing 6-1 associates the same ActionListener with every 
JMenultem: 


class MenuActionListener implements ActionListener ( 
public void actionPerformed(ActionEvent e) ( 
System.out.println("Selected: " + e.getActionCommand()); 
J 
) 


However, more frequently, you would associate a different action with each item, so that 
each menu item can respond differently. 


Tip Instead of creating a custom ActionListener for the component, and adding it as a listener, you 
can also create a custom Action and call setAction() on the component. 


Listening to JMenultem Events with a MenuKeyListener 


The MenuKeyEvent is a special kind of KeyEvent used internally by the user interface classes for 
a JMenu and JMenultem, allowing the components to listen for when their keyboard mnemonic 
is pressed. To listen for this keyboard input, each menu component registers a MenuKeyListener 
to pay attention to the appropriate input. Ifthe keyboard mnemonic is pressed, the event is 
consumed and not passed to any registered listeners. Ifthe keyboard mnemonicis not pressed, 
any registered key listeners (instead of menu key listeners) are notified. 

The MenuKeyListener interface definition follows: 


public interface MenuKeyListener extends EventListener £ 
public void menuKeyPressed(MenuKeyEvent e); 
public void menuKeyReleased(MenuKeyEvent e); 
public void menuKeyTyped(MenuKeyEvent e); 


J 


Normally, you wouldn't register objects as this type of listener yourself, although you could 
if you wanted to. If you do, and if a MenuKeyEvent happens (that is, a key is pressed/released), 
every JMenu on the JMenuBar will be notified, as will every JMenuTtem (or subclass) on an open 
menu with a registered MenuKeyListener. That includes disabled menu items so that they can 
consume a pressed mnemonic. The definition ofthe MenuKeyEvent class follows: 
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public class MenuKeyEvent extends KeyEvent ( 
public MenuKeyEvent (Component source, int id, long when, int modifiers, 
int keyCode, char keyChar, MenuElement path[], MenuSelectionManager mgr); 
public MenuSelectionManager getMenuSelectionManager(); 
public MenuElement[] getPath(); 


) 


It's the job of the MenuSelectionManager to determine the current selection path. The 
selection path is the set of menu elements from the top-level JMenu on the JMenuBar to the 
selected components. For the most part, the manager works behind the scenes, and you never 
need to worry about it. 


Listening to JMenultem Events with a MenuDragMouseListener 


Like MenuKeyEvent, the MenuDragMouseEvent is a special kind of event used internally by the user 
interface classes for JMenu and JMenuTtem. As its name implies, the MenuDragMouseEvent is a 
special kind of MouseEvent. By monitoring when a mouse is moved within an open menu, the 
user interface classes use the listener to maintain the selection path, thus determining the 
currently selected menu item. Its definition follows: 


public interface MenuDragMouseListener extends EventListener ( 
public void menuDragMouseDragged(MenuDragMouseEvent e); 
public void menuDragMouseEntered(MenuDragMouseEvent e); 
public void menuDragMouseExited(MenuDragMouseEvent e); 
public void menuDragMouseReleased(MenuDragMouseEvent e); 


) 


As with the MenuKeyListener, normally you don't listen for this event yourself. If you're 
interested in when a menu or submenu is about to be displayed, the better listener to register 
is the MenuListener, which can be registered with the JMenu, but not with an individual JMenuTtem. 
You'll look at this in the next section, which describes JMenu. 

The definition of the MenuDragMouseEvent class, the argument to each of the 
MenuDragMouseListener methods, is as follows: 


public class MenuDragMouseEvent extends MouseEvent ( 
public MenuDragMouseEvent (Component source, int id, long when, int modifiers, 
int x, int y, int clickCount, boolean popupTrigger, MenuElement path[ ], 
MenuSelectionManager mgr); 
public MenuSelectionManager getMenuSelectionManager(); 
public MenuElement[] getPath(); 


) 


Customizing a JMenultem Look and Feel 


As with the JMenuBar, the predefined look and feel types each provide a different JMenuTtem 
appearance and set of default UTResource values. Figure 6-3 showed the appearance ofthe 
JMenuItem component for the preinstalled set: Motif, Windows, and Ocean. 

The available set ofUTResource-related properties for a JMenuTtem are shown in Table 6-4. 
The JMenuTtem component offers 20 different properties. 
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Table 6-4. JMenultem UlResource Elements 


Property String Object Type 
enultem.acceleratorDelimiter String 
enultem.acceleratorFont Font 
enultem.acceleratorForeground Color 
enultem.acceleratorSelectionForeground Color 
enuTtem.actionMap ActionMap 
enultem.arrowIcon Icon 
enultem.background Color 
enultem.border Border 
enultem.borderPainted Boolean 
enultem.checkIcon Icon 
enulTtem. commandSound String 
enultem. disabledForeground Color 
enultem. font Font 
enultem. foreground Color 
enuTtem.margin Insets 
enultem.opaque Boolean 
enultem.selectionBackground Color 
enultem.selectionForeground Color 
enultem.textlconGap Integer 
enuTtemUI String 

JMenu Class 


The JMenu component is the basic menu item container that is placed on a JMenuBar. When a 
JMenu is selected, the menu displays the contained menu items within a JPopupMenu. As with 
JMenulItem, the data model for the JMenu is an implementation of ButtonModel, or more specifically, 
DefaultButtonModel 


Creating JMenu Components 


Four constructors for JMenu allow you to initialize the string label of the menu if desired: 
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public JMenu() 
JMenu jMenu = new JMenu(); 


public JMenu(String label) 
JMenu jMenu = new JMenu("File"); 


public JMenu(String label, boolean useTear0ffs) 


public JMenu(Action action) 
Action action = ...; 
JMenu jMenu = new JMenu(action); 


One constructor is for using a tear-off menu. However, tear-off menus aren't currently 
supported; therefore, the argument is ignored. The fourth constructor pulls the properties of 
the menu from an Action. 


Note Tear-off menus are menus that appear in a window and remain open after selection, instead of 
automatically closing. 


Adding Menu Items to a JMenu 


Once you have a JMenu, you need to add JMenultem objects to it; otherwise, the menu will not 
display any choices. There are five methods for adding menu items defined within JMenu and 
one for adding a separator: 


public JMenultem add(JMenultem menultem) ; 

public JMenultem add(String label); 

public Component add(Component component); 

public Component add(Component component, int index); 
public JMenultem add(Action action); 

public void addSeparator(); 


In Listing 6-1 earlier in this chapter, all the JMenuTtem components were added to JMenu 
components with the first add() method. As a shortcut, you can pass the text label for a JMenuItem 
to the add() method of JMenu. This will create the menu item, set its label, and pass back the 
new menu item component. You can then bind a menu item event handler to this newly 
obtained menu item. The third add() method shows that you can place any Component ona 
JMenu, not solely a JMenuTtem. The fourth adad() lets you position the component. The last add (>) 
variety, with the Action argument, will be discussed in the next section of this chapter. 

You can add separator bars with the addSeparator() method of JMenu. For instance, in 
Listing 6-1, the File menu was created with code similar to the following: 
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JMenu fileMenu = new JMenu("File"); 

JMenultem newMenultem = new JMenultem("New"); 
fileMenu.add(newMenultem); 

JMenultem openMenultem = new JMenultem("Open"); 
fileMenu.add(openMenultem); 

JMenultem closeMenultem = new JMenultem("Close"); 
fileMenu.add(closeMenultem); 
fileMenu.addSeparator(); 

JMenultem saveMenultem = new JMenultem("Save"); 
fileMenu.add(saveMenultem) ; 
fileMenu.addSeparator(); 

JMenultem exitMenultem = new JMenultem("Exit"); 
fileMenu.add(exitMenultem); 


Notice the addSeparator() calls wrapped around the call to add the Save menu item. 
In addition to adding menu items at the end of a menu, you can insert them at specific 
positions or insert a separator at a specific position, as follows: 


public JMenultem insert(JMenultem menultem, int pos); 
public JMenultem insert(Action a, int pos); 
public void insertSeparator(int pos); 


When a menu item is added to a JMenu, it's added to an internal JPopupMenu. 


Using Action Objects with Menus 


The Action interface and its associated classes are described in Chapter 2. An Action is an 
extension ofthe ActionListener interface and contains some special properties for customizing 
components associated with its implementations. 

With the help of the AbstractAction implementation, you can easily define text labels, 
icons, mnemonics, tooltip text, enabled status, and an ActionListener apart from a component. 
Then you can create a component with an associated Action and not need to give the component 
a text label, icon, mnemonics, tooltip text, enabled status, or ActionListener, because those 
attributes would come from the Action. For a more complete description, refer to Chapter 2. 

To demonstrate, Listing 6-2 creates a specific implementation of AbstractAction and adds 
it to a JMenu multiple times. Once the Action is added to a JMenu, selecting the JMenuTtem will 
display a pop-up dialog box with the help ofthe JOptionPane class, a topic covered in Chapter 9. 


Listing 6-2. About Action Definition 


import java.awt.*; 
import java.awt.event.*; 
import javax.swing.*; 
public class ShowAction extends AbstractAction ( 
Component parentComponent; 
public ShowAction(Component parentComponent) ( 
super("About"); 
putValue(Action.MNEMONIC_KEY, new Integer(KeyEvent.VK_A)); 
this.parentComponent = parentComponent; 


J 
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public void actionPerformed(ActionEvent actionEvent) ( 
Runnable runnable = new Runnable() ( 
public void run() £ 
JOptionPane.shonMessageDialog( 
parentComponent, "About Swing", 
"About Box V2.0", JOptionPane. INFORMATION MESSAGE); 
) 
5 
EventQueue.invokelLater(runnable); 
) 
J 


The next source creates a ShowAction and a JMenuTtem for the File and Edit menus in the 
sample program (Listing 6-1). Without explicitly setting the menu item properties, it will then 
have an “About” text label and an A mnemonic, and will perform the defined actionPerformed() 
method as its ActionListener. In fact, you can create the Action once, and then associate it 
with as many places as necessary (or other components that support adding Action objects). 


Action showAction = new ShowAction(aComponent)'; 
JMenultem fileAbout = new JMenultem(showAction); 
fileMenu.add(fileAbout); 
JMenultem editAbout = new JMenulItem(showAction); 
editMenu.add(editAbout); 


One complexity-busting side effect when using AbstractAction is that it lets you disable 
the Action with setEnabled(false), which, in turn, will disable all components created fromit. 


JMenu Properties 


Besides the 100-plus inherited properties of JMenu, 16 properties are available from JMenu-specific 
methods, as shown in Table 6-5. Several of the properties override the behavior of the inherited 
properties. For instance, the setter method for the accelerator property throws an error if you 
try to assign such a property. In other words, accelerators aren't supported within JMenu objects. 
The remaining properties describe the current state ofthe JMenu object and its contained menu 
components. 


Table 6-5. JMenu Properties 


Property Name Data Type Access 

accelerator KeyStroke Write-only 
accessibleContext AccessibleContext Read-only 
component Component Read-only 
delay int Read-write 
itemCount int Read-only 
menuComponentCount int Read-only 


menuComponents Component[ ] Read-only 
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Table 6-5. JMenu Properties (Continued) 


Property Name Data Type Access 
menuListeners MenuListener[ ] Read-only 

model ButtonModel Write-only bound 
popupMenu JPopupMenu Read-only 
popupMenuVisible boolean Read-write 
selected boolean Read-write 
subElements MenuElement[ ] Read-only 
tear0ff boolean Read-only 
topLevelMenu boolean Read-only 
UlClassID String Read-only 


Tip Keep in mind that many property methods are inherited and that the parent class might offer a getter 
method where the current class defines only a new setter method, or vice versa. 


The delay property represents the value for the time that elapses between selection 
of a JMenu and posting of the JPopupMenu. By default, this value is zero, meaning that the 
submenu will appear immediately. Trying to set the value to a negative setting will throw 
an I1legalArgumentException. 


Caution Since there is no support for tear-off menus, if you try to access the tearOff property, an error 
will be thrown. 


Selecting Menu Components 


Normally, you don't need to listen for the selection of Menu components. You listen for only 
selection ofindividual JMenuItem components. Nevertheless, you may be interested in the 
different ways that ChangeEvent works with a JMenu as compared with a JMenultem. In addition, 
a MenuEvent can notify you whenever a menu is posted or canceled. 
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Listening to JMenu Events with a ChangeListener 


As with a JMenultem, you can register a Changel istener with a JMenu ifyou're interested in making 
changes to the underlying ButtonModel. Surprisingly, the only possible state change to the 
ButtonModel with a JMenu is with the selected property. When selected, the JMenu displays its 
menu items. When not selected, the pop-up goes away. 


Listening to JMenu Events with a MenuListener 


The better way to listen for when a pop-up is displayed or hidden is by registeringMenuListener 
objects with your JMenu objects. Its definition follows: 


public interface MenulListener extends EventListener ( 
public void menuCanceled(MenuEvent e); 
public void menuDeselected(MenuEvent e); 
public void menuSelected(MenuEvent e); 


) 


With a registered MenuListener, you're notified when a JMenu is selected before the pop-up 
menu is opened with the menu's choices. This allows you to customize its menu choices on the 
fly at runtime, with some potential interaction performance penalties. Besides being told when 
the associated pop-up menu is to be posted, you're also notified when the menu has been 
deselected and when the menu has been canceled. As the following MenuEvent class definition 
shows, the only piece of information that comes with the event is the source (the menu): 


public class MenuEvent extends EventObject ( 
public MenuEvent(Object source); 


) 


Tip !f you choose to customize the items on a JMenu dynamically, be sure to call revalidate(), 
because the component waits until you are done before updating the display. 


Customizing a JMenu Look and Feel 


As with the JMenuBar and JMenultem, the predefined look and feel classes provide a different 
JMenu appearance and set of default UTResource values. Figure 6-3 shows the appearance of the 
JMenu object for the preinstalled set of look and feel types. 

The available set ofUTResource-related properties for a Menu is shown in Table 6-6. For the 
JMenu component, there are 30 different properties. 
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Table 6-6. JMenu UlResource Elements 
Property String 
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Object Type 
Color 
String 
Font 
Color 
Color 
ActionMap 
Icon 
Color 
Border 
Boolean 
Icon 
Integer 
Color 
Font 
Color 
Insets 
Integer 
Integer 
Boolean 
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Color 
int[ ] 
Integer 
Integer 
Integer 
Boolean 
Color 
Color 
Color 
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JSeparator Class 


The JSeparator class is a special component that acts as a separator on a JMenu. The JPopupMenu 
and JToo1Bar classes also support separators, but each uses its own subclass of JSeparator. In 
addition to being placed on a menu, the JSeparator can be used anywhere you want to use a 
horizontal or vertical line to separate different areas of a screen. 

The JSeparator is strictly a visual component; therefore, it has no data model. 


Creating JSeparator Components 


To create a separator for a JMenu, you don't directly create a JSeparator, although you can. 
Instead, you call the addSeparator() method of JMenu, and the menu will create the separator 
and add the separator as its next item. The fact that it's a JSeparator (which isn't a JMenultem 
subclass) is hidden. There's also an insertSeparator(int index) method of JMenu that allows 
you to add a separator at a specific position on the menu, that isn't necessarily the next slot. 

If you plan to use a JSeparator away from a menu (for example, to visually separate two 
panels in a layout), you should use one of the two constructors for JSeparator: 


public JSeparator() 
JSeparator jSeparator = new JSeparator(); 


public JSeparator(int orientation) 
JSeparator jSeparator = new JSeparator(JSeparator.VERTICAL); 


These constructors allow you to create a horizontal or vertical separator. Ifan orientation 
isn't specified, the orientation is horizontal. Ifyou want to explicitly specify an orientation, you 
use either ofthe JSeparator constants of HORIZONTAL and VERTICAL. 


JSeparator Properties 


After you have a JSeparator, you add it to the screen like any other component. The initial 
dimensions of the component are empty (zero width and height), so ifthe layout manager of 
the screen asks the component what size it would like to be, the separator will reply that it 
needs no space. On the other hand, ifthe layout manager offers a certain amount of space, the 
separator will use the space ifthe orientation is appropriate. For instance, adding a horizontal 
JSeparator to the north side of a BorderLayout panel draws a separator line across the screen. 
However, adding a horizontal JSeparator to the east side of the same panel would result in 
nothing being drawn. For a vertical JSeparator, the behavior is reversed: The north side would 
be empty and a vertical line would appear on the east side. 

The four properties of JSeparator are listed in Table 6-7. 


Table 6-7. JSeparator Properties 


Property Name Data Type Access 
accessibleContext AccessibleContext Read-only 
orientation int Read-write bound 
UI SeparatorUl Read-write bound 


UlClassID String Read-only 
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Caution If the orientation property isn't set to a value equivalent to either JSeparator.HORIZONTAL or 
JSeparator.VERTICAL, an 111legalArgumentException is thrown. 


Customizing a JSeparator Look and Feel 


The appearance of the JSeparator under the preinstalled set of look and feel types is shown 
with the other menu components in Figure 6-3. 

The available set ofUTResource-related properties for a JSeparator is shown in Table 6-8. 
For the JSeparator component, five different properties are available. 


Table 6-8. JSeparator UlResource Elements 


Property String Object Type 
Separator.background Color 
Separator.foreground Color 
Separator.insets Insets 
Separator.thickness Integer 
Separatorul String 


Caution Two additional properties, high1ight and shadow, are present but deprecated and should not 
be used. 


JPopupMenu Class 


The JPopupMenu component is the container for pop-up menu components, displayable anywhere 
and used for support by JMenu. When a programmer-defined triggering event happens, you 
display the JPopupMenu, and the menu displays the contained menu components. Like JMenuBar, 
JPopupMenu uses the SingleSelectionModel to manage the currently selected element. 


Creating JPopupMenu Components 


There are two constructors for JPopupMenu: 


public JPopupMenu() 
JPopupMenu jPopupMenu = new JPopupMenu(); 


public JPopupMenu(String title) 
JPopupMenu jPopupMenu = new JPopupMenu("Welcome"); 
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Only one allows you to initialize the title for the menu, if desired. What happens with the 
title depends on the installed look and feel. The currently installed look and feel may ignore 
the title. 


Adding Menu Items to a JPopupMenu 


As with a Menu, once you have a JPopupMenu, you need to add menu item objects to it; other- 
wise, the menu will be empty. There are three JPopupMenu methods for adding menu items and 
one for adding a separator: 


public JMenultem add(JMenultem menultem); 
public JMenultem add(String label); 
public JMenultem add(Action action); 
public void addSeparator(); 


In addition, an add() method is inherited from Container for adding regular AWT 
components: 


public Component add(Component component); 


Note !t generally isn't wise to mix lightweight Swing components with heavyweight AWT components. 
However, because pop-up menus are more apt to be on top, it's less of an issue in this case. 


The natural way of adding menu items is with the first add() method. You create the menu 
item independently of the pop-up menu, including defining its behavior, and then you attach it 
to the menu. With the second variety of add(), you must attach an event handler to the menu 
item returned from the method; otherwise, the menu choice won't respond when selected. The 
following source demonstrates the two approaches. Which you use depends entirely on your 
preference. A visual programming environment like JBuilder will use the first. Because the 
first approach is inherently less complex, most, if not all, programmers should also use 
the first approach. 


JPopupMenu popupenu = new JPopupMenu(); 
ActionListener anActionListener = ...; 

// The first way 

JMenultem firstItem = new JMenultem("Hello"); 
firstItem.addActionListener(anActionListener); 
popupMenu.add(firstItem); 

// The second way 

JMenuTtem secondItem = popupMenu.add("World"); 
secondItem.addActionListener(anActionListener); 


Using an Action to create a menu item works the same with JPopupMenu as it does with 
JMenu. However, according to the Javadoc for the JPopupMenu class, using the Action variety of 
the add() method is discouraged. Instead, pass the Action to the constructor for JMenultem, or 
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configure it with setAction(), and then add that to the JPopupMenu. Why the method isn't just 
deprecated isn't clear. 

Lastly, you can add a menu separator with the addSeparator() method. 

As well as adding menu items at the end ofa menu, you can insert them at specific positions or 
insert a separator at a specific position: 


public JMenultem insert(Component component, int position); 
public JMenultem insert(Action action, int position); 


There's no insertSeparator() method as there is with JMenu. But you can use the 
add(Component component, int position) method inherited from Container. If you want to 
remove components, use the remove (Component component) method specific to JPopupMenu. 


Note Accelerators on attached JMenuTtem objects are ignored. Mnemonics might also be ignored 
depending on the currently installed look and feel. 


Displaying the JPopupMenu 


Unlike the JMenu, simply populating the pop-up menu isn't sufficient to use it. You need to 
associate the pop-up menu with an appropriate component. Prior to the 5.0 release of Swing, 
you needed to add event-handling code to trigger the display ofthe pop-up menu. Now, all you 
need to do is call the setComponentPopupMenu() method for the Swing component you wish to 
associate the pop-up menu with. When the platform-specific triggering event happens, the 
pop-up menu is automatically displayed. 


Note Why change the way pop-up menu display is triggered? The old code was very tightly tied to mouse 
events. lt didn't connect well with the accessibility framework. And the same code was being added every- 
where to just show the pop-up menu at the x, y coordinates of the invoker. 


You simply need to create an instance of JPopupMenu and attach it to any component you 
want to have display the pop-up menu, as follows: 


JPopupMenu popupMenu = ...; 
aComponent .setComponentPopupMenu(popupMenu); 


The methods of JComponent that are important to pop-up menus are 
getComponentPopupMenu(), setComponentPopupMenu(), getInheritsPopupMenu(), 
setInheritsPopupMenu(), and getPopupLocation(). The setInheritsPopupMenu() method 
accepts a boolean argument. When true, and no component pop-up menu has been directly 
set for the component, the parent container will be explored for a pop-up. 


JPopupMenu Properties 
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The 16 properties of JPopupMenu are listed in Table 6-9. Many more properties are also inherited 
through JComponent, Container, and Component. 


Table 6-9. JPopupMenu Properties 


Property Name Data Type Access 
accessibleContext  AccessibleContext  Read-omly 
borderPainted boolean Read-write 
component Component Read-only 
invoker Component Read-only 

label String Read-write bound 
lightWeightPopupEnabled boolean Read-write 

margin Insets Read-only 
menuKeyListeners MenuKeyListener[ ] Read-only 
popupMenuListeners PopupMenuListener[ ] Read-only 
popupSize Dimension Write-only 
selected Component Write-only 
selectionModel SingleSelectionModel Read-write 
subElements MenuElement[ ] Read-only 

UI PopupMenuUI Read-write bound 
UlClassID String Read-only 
visible boolean 


Read-write 


The most interesting property of JPopupMenu is lightWeightPopupEnabled. Normally, the 


JPopupMenu tries to avoid creating new heavyweight components for displaying its menu items. 
Instead, the pop-up menu uses a JPanel when the JPopupMenu can be displayed completely 
within the outermost window boundaries. Otherwise, if the menu items don't fit, the JPopupMenu 
uses a JWindow. If, however, you're mixing lightweight and heavyweight components on different 
window layers, displaying the pop-up within a JPanel might not work, because a heavyweight 
component displayed in the layer ofthe menu will appear in front ofthe JPanel. To correct this 
behavior, the pop-up menu can use a Panel for displaying the menu choices. By default, the 
JPopupMenu never uses a Panel. 
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Note When the JPopupMenu is displayed in either a JPanel or a Panel, the outermost window relies on 
the layering effect of the JRootPane to ensure that the pop-up panel is displayed at the appropriate position 
in front of the other components. Chapter 8 describes the JRootPane class in more detail. 


If you need to enable the display of a Panel, you can configure it at the individual JPopupMenu 
level or for your entire applet or application. At the individual pop-up level, just set the 
lightWeightPopupEnabled property to false. At the system level, this is done as follows: 


// From now on, all JPopupMenus will be heavyweight 
JPopupMenu.setDefaultLightWeightPopupEnabled(false); 


The method must be called before creating the pop-up menu. JPopupMenu objects created 
before the change will have the original value (the default is true). 


Watching for Pop-Up Menu Visibility 


Like the JMenu, the JPopupMenu has a special event/listener combination to watch for when the 
pop-up menu is about to become visible, invisible, or canceled. The event is PopupMenuEvent, 
and the listeneris PopupMenuListener. The event class simply references the source pop-up 
menu of the event. 


public class PopupMenuEvent extends EventObject ( 
public PopupMenuEvent(Object source); 
J 


When a JPopupMenu fires the event, any registered PopupMenuListener objects are notified 
through one ofits three interface methods. This lets you customize the current menu items 
based on the system state or who/what the pop-up menu invoker happens to be. The 
PopupMenuListener interface definition follows: 


public interface PopupMenulListener extends EventListener ( 
public void popupMenuCanceled(PopupMenuEvent e); 
public void popupMenuWillBecomeInvisible(PopupMenuEvent e); 
public void popupMenuWillBecomeVisible(PopupMenuEvent e); 

J 


Customizing a JPopupMenu Look and Feel 


Each installable Swing look and feel provides a different JPopupMenu appearance and set of 
default UIResource values. Figure 6-6 shows the appearance of the JPopupMenu component for 
the preinstalled set of look and feel types: Motif, Windows, and Ocean. Notice that of the 
predefined look and feel classes, only Motif uses the title property of the JPopupMenu. 
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AE 1012 


Motif Windows 


-I0/x 


Ocean 


Figure 6-6. JPopupMenu under different look and feel types 


The available set ofUTResource-related properties for a JPopupMenu is shown in Table 6-10. 
For the JPopupMenu component, there are five different properties. 


Table 6-10. JPopupMenu UlResource Elements 


Property String Object Type 
PopupMenu.actionMap ActionMap 
PopupMenu. background Color 
PopupMenu. border Border 
PopupMenu.consumeEventOnClose Boolean 
PopupMenu. font Font 
PopupMenu. foreground Color 
PopupMenu. popupSound String 
PopupMenu.selectedWindowInputMapBindings Object[ ] 
PopupMenu.selectedWindowInputMapBindings.RightToLeft Object[ ] 
PopupMenuSeparatorUl String 
PopupMenuUI String 
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JPopupMenu.Separator Class 


The JPopupMenu class maintains its own separator to permit a custom look and feel forthe separator 
when it's on a JPopupMenu. This custom separator is an inner class to the JPopupMenu. 

When you call the addSeparator() of JPopupMenu, an instance of this class is automatically 
created and added to the pop-up menu. In addition, you can create this separator by calling its 
no-argument constructor: 


JSeparator popupSeparator = new JPopupMenu.Separator(); 


Both methods create a horizontal separator. 


Note If you want to change the orientation of the separator, you must call the setOrientation() 
method inherited from JSeparator with an argument of JPopupMenu. Separator . VERTICAL. However, 
having a vertical separator on a pop-up menu is inappropriate. 


A Complete Pop-Up Menu Usage Example 


The program in Listing 6-3 puts together all the pieces of using a JPopupMenu, including listening 
for selection of all the items on the menu, as well as listening for when it's displayed. The output for 
the program is shown in Figure 6-7, with the pop-up visible. 


£ PopupSample Example 101 x/ 


Copy 
Paste 


Find 


Figure 6-7. JPopupMenu usage example output 


Listing 6-3. PopupSample Class Definition 


import java.awt.*; 

import java.awt.event.*; 
import javax.swing.*; 
import javax.swing.event.*; 


public class PopupSample ( 
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// Define ActionListener 
static class PopupActionListener implements ActionListener ( 
public void actionPerformed(ActionEvent actionEvent) ( 


J 


J 


System.out.println("Selected: 


" 


+ actionEvent.getActionCommand()); 


// Define PopupMenuListener 
static class MyPopupMenuListener implements PopupMenuListener £ 
public void popupMenuCanceled(PopupMenuEvent popupMenuEvent) £ 


J 


J 


System.out.println("Canceled"); 


public void popupMenuWillBecomeInvisible(PopupMenuEvent popupMenuEvent) f 


J 


System.out.println("Becoming Invisible"); 


public void popupMenuWillBecomeVisible(PopupMenuEvent popupMenuEvent) ( 


J 


System.out.println("Becoming Visible"); 


public static void main(final String args[]) ( 
Runnable runner = new Runnable() 4 


public void run() £ 


// Create frame 
JFrame frame = new JFrame("PopupSample Example"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


ActionListener actionListener = new PopupActionListener(); 
PopupMenuListener popupMenuListener = new MyPopupMenuListener(); 


// Create popup menu, attach popup menu listener 
JPopupMenu popupMenu = new JPopupMenu("Title"); 
popupMenu.addPopupMenuListener(popupMenuListener); 


// Cut 

JMenultem cutMenultem = new JMenultem("Cut"); 
cutMenultem.addActionListener(actionListener); 
popupMenu.add(cutMenuTtem); 


// Copy 

JMenultem copyMenultem = new JMenulItem("Copy"); 
copyMenultem.addActionListener(actionListener); 
popupMenu.add(copyMenultem); 


183 


184 CHAPTER 6 SWING MENUS AND TOOLBARS 


// Paste 

JMenultem pasteMenultem = new JMenultem("Paste"); 
pasteMenultem.addActionListener(actionListener); 
pasteMenultem.setEnabled(false); 
popupMenu.add(pasteMenultem); 


// Separator 
popupMenu.addSeparator(); 


// Find 

JMenultem findMenultem = new JMenultem("Find"); 
findMenultem.addActionListener(actionListener); 
popupMenu.add(findMenultem); 

JButton label = new JButton(); 
frame.add(label); 
label.setComponentPopupMenu(popupMenu) ; 


frame.setSize(350, 250); 
frame.setVisible(true); 
) 
E 
EventQueue.invokeLater(runner); 
) 
) 


JCheckBoxMenultem Class 


Swing's JCheckBoxMenuTtem component behaves as if you have a JCheckBox on a menu as a 
JMenultem. The data model for the menu item is the ToggleButtonModel, described in Chapter 5. 

It allows the menu item to have a selected or unselected state, while showing an appropriate 
icon for the state. Because the data model is the ToggleButtonModel, when JCheckBoxMenultem 
is placed in a ButtonGroup, only one component in the group is ever selected. However, this 
isn't the natural way to use a JCheckBoxMenuTtem and is likely to confuse users. Ifyou need this 
behavior, use JRadioButtonMenultenm, as described later in this chapter. 


Creating JCheckBoxMenultem Components 


There are seven constructors for JCheckBoxMenultem. They allow you to initialize the text label, 
icon, and initial state. 


public JCheckBoxMenuTtem() 
JCheckBoxMenultem jCheckBoxMenultem = new JCheckBoxMenultem(); 


public JCheckBoxMenuItem(String text) 
JCheckBoxMenultem jCheckBoxMenultem = new JCheckBoxMenultem("Boy"); 
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public JCheckBoxMenuItem(Icon icon) 
Icon boylcon = new Imagelcon("boy-1.jpg"); 
JCheckBoxMenultem jCheckBoxMenultem = new JCheckBoxMenuItem(boyIcon); 


public JCheckBoxMenuItem(String text, Icon icon) 
JCheckBoxMenultem jCheckBoxMenultem = new JCheckBoxMenulItem("Boy", boyIcon); 


public JCheckBoxMenuItem(String text, boolean state) 
JCheckBoxMenultem jCheckBoxMenultem = new JCheckBoxMenultem("Girl", true); 


public JCheckBoxMenuItem(String text, Icon icon, boolean state) 
Icon girlIcon = new Imagelcon("girl-r.jpg"); 
JCheckBoxMenultem jCheckBoxMenultem = new JCheckBoxMenulItem("Girl1", girlIcon, true); 


public JCheckBoxMenuItem(Action action) 
Action action = ...; 
JCheckBoxMenultem jCheckBoxMenultem = new JCheckBoxMenultem(action); 


Unlike the JCheckBox, the icon is part of the label and not a separate device to indicate 
whether something is checked. If either the text label or the icon isn't passed to the constructor, 
that part of the item label will be set to its default value of empty. By default, a JCheckBoxMenuTtemis 
unselected. 


Note Creating a JCheckBoxMenuItem with an icon has no effect on the appearance of the check box 
next to the menu item. It's strictly part of the label for the JCheckBoxMenultem. 


JCheckBoxMenultem Properties 


Most of the JCheckBoxMenultem properties are inherited from the many superclasses of 
JCheckBoxMenultem. Table 6-11 lists the four properties defined by JCheckBoxMenultem. 


Table 6-11. JCheckBoxMenultem Properties 


Property Name Data Type Access 

accessibleContext AccessibleContext Read-only 
selectedObjects Object[] Read-only 
state boolean Read-write 


UlClassID String Read-only 
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Handling JCheckBoxMenultem Selection Events 


With a JCheckBoxMenultem, you can attach many different listeners for a great variety of events: 
+ MenuDragMouseListener and MenuKeyListener from JMenultem 
+ ActionListener, ChangeListener, and ItemListener from AbstractButton 
+ AncestorListener and VetoableChangeListener from JComponent 
+ ContainerListener and PropertyChangeListener from Container 


+ ComponentListener, FocusListener, HierarchyBoundsListener, HierarchyListener, 
InputMethodListener, KeyListener, MouseListener, MouseMotionListener, and 
MousewheelListener from Component 


Although you can listen for 18 different types of events, the most interesting are 
ActionEvent and ItemEvent, described next. 


Listening to JCheckBoxMenultem Events with an ActionListener 


Attaching an ActionListener to a JCheckBoxMenultem allows you to find out when the menu 
item is selected. The listener is told of the selection, but not of the new state. To find out the 
selected state, you must get the model for the event source and query the selection state, as the 
following sample ActionListener source shows. This listener modifies both the check box text 
and the icon label, based on the current selection state. 


ActionListener aListener = new ActionListener() ( 
public void actionPerformed(ActionEvent event) ( 
Icon girlIcon = new Imagelcon("girl-1.jpg"); 
Icon boylcon = new Imagelcon("boy-r.jpg"); 
AbstractButton aButton = (AbstractButton)event.getSource(); 
boolean selected = aButton.getModel().isSelected(); 
String newLabel; 
Icon newlIcon; 
if (selected) ( 
newLabel = "Girl"; 
newIcon = girlIcon; 
y else £ 
newLabel = "Boy"; 
newIcon = boyIcon; 
J 
aButton.setText(newLabel); 
aButton.setIcon(newlcon); 
) 
5 


Note Keep in mind that you can also associate an Action from the constructor that can do the 
same thing. 
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Listening to JCheckBoxMenultem with an ItemListener 


If you listen for JCheckBoxMenuitem selection with an ItemListener, you don't need to query the 
event source for the selection state—the event already carries that information. Based on this 
state, you respond accordingly. Re-creating the ActionListener behavior with an ItemListener 
requires just a few minor changes to the previously listed source, as follows: 


ItemListener ilistener = new ItemListener() ( 
public void itemStateChanged(ItemEvent event) ( 
Icon girlIcon = new Imagelcon("girl-r.jpg"); 
Icon boylcon = new Imagelcon("boy-r.;jpg"); 
AbstractButton aButton = (AbstractButton)event.getSource(); 
int state = event.getStateChange(); 
String newLabel; 
Icon newlIcon; 
if (state == ItemEvent.SELECTED) £ 
newLabel = "Girl"; 
newIcon = girlIcon; 
j else £ 
newLabel = "Boy"; 
newIcon = boyIcon; 
, 
aButton.setText(newLabel); 
aButton.setlIcon(newIcon); 
) 
E 


Customizing a JCheckBoxMenultem Look and Feel 


The appearance of the JCheckBoxMenuTtem under the preinstalled set of look and feel types is 
shown with the other menu components in Figure 6-3. 

The available set of UTResource-related properties for a JCheckBoxMenuItem is shown in 
Table 6-12. The JCheckBoxMenuTtem component has 19 different properties. 


Table 6-12. JCheckBoxMenultem UlResource Elements 


Property String Object Type 
CheckBoxMenultem.acceleratorFont Font 
CheckBoxMenultem.acceleratorForeground Color 
CheckBoxMenultem.acceleratorSelectionForeground Color 
CheckBoxMenultem.actionMap ActionMap 
CheckBoxMenuTtem.arrowIcon Icon 
CheckBoxMenultem. background Color 
CheckBoxMenultem. border Border 
CheckBoxMenultem.borderPainted Boolean 
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Table 6-12. JCheckBoxMenultem UlResource Elements (Continued) 


Property String 
CheckBoxMenultem. checkIcon 


CheckBoxMenultem. commandSound 


CheckBoxMenuTtem.disabledForeground 


CheckBoxMenultem. font 
CheckBoxMenuItem. foreground 
CheckBoxMenuTtem.gradient 
CheckBoxMenuTtem.margin 


CheckBoxMenuTtem.opaque 


CheckBoxMenuTtem.selectionBackground 


CheckBoxMenuTtem.selectionForeground 


CheckBoxMenuItemUl 


Object Type 
Icon 
String 
Color 
Font 
Color 
List 
Insets 
Boolean 
Color 
Color 


String 


The Icon associated with the CheckBoxMenuTtem. checkIcon property key is the one displayed on 
the JCheckBoxMenultem. Ifyou don't like the defaulticon, you can change it with the following line 
of source, assuming the new icon has already been defined and created: 


UlManager.put("CheckBoxMenuItem.checkIcon", somelcon); 


For this new icon to display an appropriate selected image, the Icon implementation 
must check the state of the associated menu component within its paintIcon() method. The 
DiamondIcon created in Chapter 4 wouldn't work for thisicon because it doesn't ask the compo- 
nent for its state. Instead, the state is fixed at constructor time. Listing 6-4 shows a class that 


represents one icon that could be used. 


Listing 6-4. State-Aware Icon Definition 


import java.awt.*; 
import javax.swing.*; 


public class DiamondAbstractButtonStatelcon implements Icon f 


private Color color; 
private Polygon polygon; 


this.color = color; 
initPolygon(); 
) 


private final int width = 10; 
private final int height = 10; 


public DiamondAbstractButtonStatelcon(Color color) ( 
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private void initPolygon() ( 
polygon = new Polygon(); 
int halfWidth = width/2; 
int halfHeight = height/2; 
polygon.addPoint (O, halfHeight); 
polygon.addPoint (halfWidth, 0); 
polygon.addPoint (width, halfHeight); 
polygon.addPoint (halfWidth, height); 
) 
public int getIconHeight() ( 
return width; 
y 
public int getIconWidth() ( 
return height; 
y 
public void paintIcon(Component component, Graphics g, int x, int y) ( 
boolean selected = false; 
g.setColor (color); 
g.translate (x, y); 
if (component instanceof AbstractButton) ( 
AbstractButton abstractButton = (AbstractButton)component; 
selected = abstractButton.isSelected(); 
y 
if (selected) ( 
g-fillPolygon (polygon); 


) else ( 
g.drawPolygon (polygon); 
) 
g.translate (-x, -y); 
) 


Note If the DiamondAbstractButtonStatelcon icon were used with a component that isn't an 
AbstractButton type, the icon would always be deselected, because the selection state is a property 
of AbstractButton 


JRadioButtonMenultem Class 


The JRadioButtonMenuTtem component has the longest name of all the Swing components. It 
works like a JRadioButton, but resides on a menu. When placed with other JRadioButtonMenuItem 
components within a ButtonGroup, only one component will be selected at a time. As with 
the JRadioButton, the button model for the JRadioButtonMenultem is the JToggleButton. 
ToggleButtonModel. 
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Creating JRadioButtonMenultem Components 
The JRadioButtonMenultem has seven constructors. They allow you to initialize the text label, 


icon, and initial state. 


public JCheckBoxMenuTtem() 
JCheckBoxMenultem jCheckBoxMenultem = new JCheckBoxMenultem(); 


public JCheckBoxMenuItem(String text) 
JCheckBoxMenultem jCheckBoxMenultem = new JCheckBoxMenultem("Boy"); 


public JCheckBoxMenuTtem(Icon icon) 
Icon boylcon = new Imagelcon("boy-r.jpg"); 
JCheckBoxMenultem jCheckBoxMenultem = new JCheckBoxMenulItem(boyIcon); 


public JCheckBoxMenuItem(String text, Icon icon) 
JCheckBoxMenultem jCheckBoxMenultem = new JCheckBoxMenultem("Boy", boyIcon); 


public JCheckBoxMenuItem(String text, boolean state) 
JCheckBoxMenultem jCheckBoxMenultem = new JCheckBoxMenultem("Girl", true); 


public JCheckBoxMenuItem(String text, Icon icon, boolean state) 
Icon girlIcon = new Imagelcon("girl-1.jpg"); 
JCheckBoxMenultem jCheckBoxMenultem = new JCheckBoxMenultem("Gir1", girlIcon, true); 


public JCheckBoxMenuITtem(Action action) 
Action action = ...; 
JCheckBoxMenultem jCheckBoxMenultem = new JCheckBoxMenultem(action); 


Similar to the JCheckBoxMenuItem component, the icon for the JRadioButtonMenultem is 
part of the label. This is unlike the JRadioButton, in which the icon indicates whether the radio 
button is selected. If either the text label or icon isn't part of the constructor, that part of the 
item label will be empty. By default, a JRadioButtonMenultem is unselected. If you create a 
JRadioButtonMenultem that is selected and then add it to a ButtonGroup, the button group will 
deselect the menu item if the group already has a selected item in the group. 


Note After creating JRadioButtonMenultem instances, remember to add them to a ButtonGroup, 
so they will work as a mutually exclusive group. 


Handling JRadioButtonMenultem Selection Events 


The JRadioButtonMenulItem shares the same 18 different event/listener pairs with 
JCheckBoxMenulten. To listen for selection, attaching an ActionListener is the normal 
approach. In addition, you might want to attach the same listener to all the JRadioButtonMenuTtem 
objects in a ButtonGroup—after all, they're in a group for a reason. If you use the same listener, 
that listener can employ the current selection to perform some common operation. In other 
cases, such as that in Figure 6-1, selection of any JRadioButtonMenulItem option does nothing. 
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Only when someone selects the Find menu element would the current selection ofthe ButtonGroup 
for the set of JRadioButtonMenultem components have any meaning. 


Configuring JRadioButtonMenultem Properties 


As with JCheckBoxMenultem, most of the JRadioButtonMenultem properties are inherited. The 
two shown in Table 6-13 merely override the behavior from the superclass. 


Table 6-13. JRadioButtonMenultem Properties 


Property Name Data Type Access 
accessibleContext AccessibleContext Read-only 
UlClassID String Read-only 


Customizing a JRadioButtonMenultem Look and Feel 


The appearance of the JRadioButtonMenulTtem under the preinstalled set of look and feel types 
is shown with the other menu components in Figure 6-3. 


The available set of UIResource-related properties for a JRadioButtonMenuTtem is shown in 
Table 6-14. For the JRadioButtonMenulItem component, there are 19 different properties. 


Table 6-14. JRadioButtonMenultem UlResource Elements 


Property String 


RadioButtonMenu 


RadioButtonMenu 
RadioButtonMenu 
RadioButtonMenu 
RadioButtonMenu 
RadioButtonMenu 
RadioButtonMenu 
RadioButtonMenu 
RadioButtonMenu 
RadioButtonMenu 
RadioButtonMenu 
RadioButtonMenu 


RadioButtonMenu 


RadioButtonMenul 


RadioButtonMenul 


RadioButtonMenul 


te 
te 
te 
te 
te 


Itel 


tel 


Itel 


tel 
tel 


Itel 


te 
te 
te 
te 
te 


.acceleratorFont 
.acceleratorForeground 
.acceleratorSelectionForeground 
.actionMap 

.arrowIcon 

«background 

«border 

.«borderPainted 
.CheckIcon 

. commandSound 
.disabledForeground 
«font 

.foreground 

.gradient 

.margin 


.Opaque 


Object Type 
Font 


Color 
Color 
ActionMap 
Icon 
Color 
Border 
Boolean 
Icon 
String 
Color 
Font 
Color 
List 
Insets 


Boolean 
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Table 6-14. JRadioButtonMenultem UlResource Elements (Continued) 


Property String Object Type 
RadioButtonMenultem.selectionBackground Color 
RadioButtonMenultem.selectionForeground Color 
RadioButtonMenultemUI String 


A Complete JRadioButtonMenultem Usage Example 


To help you understand the JRadioButtonMenultem usage, the program shown in Listing 6-5 
demonstrates how to put everything together, including listening for selection of all the items 
on the menu, from either an ActionListener or an ItemListener. The output for the program is 
shown in Figure 6-8. 


£: Radio Menu Example 101 x] 


O Partridge 
(2) Turtle Doves 


[0] Le French Hens 


O So Calling Birds 
% Pe 


o 


Figure 6-8. JRadioButtonMenultem usage example output 
Listing 6-5. The RadioButtonSample Class Definition 


import javax.swing.*; 
import java.awt.*; 
import java.awt.event.*; 


public class RadioButtonSample ( 
static Icon threelcon = new Imagelcon("3.gif"); 
static Icon fourlcon = new Imagelcon("4.gif"); 
static Icon fivelcon = new Imagelcon("5.gif"); 
static Icon sixIcon = new Imagelcon("6.gif"); 


public static class ButtonActionListener implements ActionListener ( 
public void actionPerformed (ActionEvent actionEvent) ( 
AbstractButton aButton = (AbstractButton)actionEvent.getSource(); 
boolean selected = aButton.getModel().isSelected(); 
System.out.println (actionEvent.getActionCommand() + 
" - selected? " + selected); 
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public static class ButtonItemListener implements ItemListener f 


J 


public void itemStateChanged(ItemEvent itemEvent) ( 


AbstractButton aButton = (AbstractButton)itemEvent.getSource(); 
int state = itemEvent.getStateChange(); 
String selected = 
((state == ItemEvent.SELECTED) ? "selected" : "not selected"); 
System.out.println (aButton.getText() + " - selected? " + selected); 


public static void main(String args[]) ( 


Runnable runner = new Runnable() £ 
public void run() £ 


final ActionListener actionListener = new ButtionActionListener(); 
final ItemListener itemListener = new ButtonItemListener(); 


JFrame frame = new JFrame("Radio Menu Example"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


JMenuBar menuBar = new JMenuBar(); 

JMenu menu = new JMenu("Menu"); 

ButtonGroup buttonGroup = new ButtonGroup(); 
menu. setMnemonic(KeyEvent.VK_M); 


JRadioButtonMenultem emptyMenultem = 

new JRadioButtonMenultenm(); 
emptyMenultem. setActionCommand ("Empty"); 
emptyMenultem.addActionListener(actionListener); 
buttonGroup.add(emptyMenultem) ; 
menu.add(emptyMenultem) ; 


JRadioButtonMenultem oneMenultem = 

new JRadioButtonMenultem("Partridge"); 
oneMenultem.addActionListener(actionListener); 
buttonGroup.add(oneMenultem); 
menu.add(oneMenultem) ; 


JRadioButtonMenultem twoMenultem = 

new JRadioButtonMenultem("Turtle Doves", true); 
twoMenultem.addActionListener(actionListener); 
buttonGroup.add(twoMenultem); 
menu. add(twoMenultem) ; 
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JRadioButtonMenultem threeMenultem = 

new JRadioButtonMenultem("French Hens", threelcon); 
threeMenultem.addItemListener(itemListener); 
buttonGroup.add(threeMenultem) ; 
menu.add(threeMenultem) ; 


JRadioButtonMenultem fourMenultem = 

new JRadioButtonMenultem("Calling Birds", fourIcon, true); 
fourMenultem.addActionListener(actionListener); 
buttonGroup.add(fourMenultem) ; 
menu. add(fourMenultem) ; 


JRadioButtonMenultem fiveMenultem = 

new JRadioButtonMenultem(fivelcon); 
fiveMenultem.addActionListener(actionListener); 
fiveMenultem.setActionCommand("Rings"); 
buttonGroup.add(fiveMenultem); 
menu.add(fiveMenultem) ; 


JRadioButtonMenultem sixMenultem = 

new JRadioButtonMenultem(sixIcon, true); 
sixMenultem.addActionListener(actionListener); 
sixMenultem.setActionCommand ("Geese"); 
buttonGroup.add(sixMenultem); 
menu.add(sixMenulItem); 


menuBar.add(menu) ; 
frame.setJMenuBar(menuBar) ; 
frame.setSize(350, 250); 
frame.setVisible(true); 
) 
E 
EventQueue.invokeLater(runner); 


J 
J 


Note Notice that the actionCommand property is set for those menu items lacking text labels. This allows 
registered ActionListener objects to determine the selected object. This is only necessary when listeners 
are shared across components. 
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Creating Custom MenuElement Components: 
The MenuElement Interface 


One thing all the selectable menu components have in common is that they implement the 

MenuE lement interface. The JSeparator doesn't implement the interface, but that's okay because 

itisn't selectable. The purpose of the MenuElement interface is to allow the MenuSelectionManager 

to notify the different menu elements as a user moves around a program's menu structure. 
As the following interface definition shows, the MenuElement interface is made up of 

five methods: 


public interface MenuElement £ 

public Component getComponent(); 

public MenuElement[] getSubElements(); 

public void menuSelectionChanged(boolean isInclude); 

public void processKeyEvent(KeyEvent event, MenuElement path[], 
MenuSelectionManager mgr); 

public void processMouseEvent(MouseEvent event, MenuElement path[ ], 
MenuSelectionManager mgr); 


The getComponent () method returns the menu's rendering component. This is usually the 
menu component itself, although that isn't a requirement. The getSubElements() method 
returns an array of any menu elements contained within this element. Ifthis menu element 
isn't the top of a submenu, the method should return a zero-length array of MenuElement 
objects, not null. 

The menuSelectionChanged() method is called whenever the menu item is placed in or 
taken out of the selection path for the menu selection manager. 

The two processKeyEvent() and processMouseEvent () methods are for processing a key 
event or mouse event that's generated over a menu. How your menu item processes events 
depends on what the component supports. For instance, unless you support accelerators, you 
probably want to respond to key events only when your menu item is in the current selection 
path. 


Note If, for example, your new menu element was something like a JComboBoxMenuTtem, where the 
MenuElement acted like a JComboBox, the processKeyEvent () might pass along the key character to 
the KeySelectionManager. See Chapter 13 for more on the KeySelectionManager. 


To demonstrate the MenuElement interface, Listing 6-6 creates a new menu component 
called a JToggleButtonMenultem. This component will look and act like a JToggleButton, although 
it can be on a menu. It's important to ensure that the menu goes away once the item is selected 
and that the component is displayed differently when in the current selection path. 
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Note Although you can add any component to a menu, if the component doesn't implement the MenuElement 
interface, it won't act properly when a mouse moves over the component or when the component is selected. 


Listing 6-6. Toggle Button As Menu Item Class Definition 


import java.awt.*; 

import java.awt.event.*; 
import javax.swing.*; 
import javax.swing.event.*; 


public class JToggleButtonMenultem extends JToggleButton implements MenuElement ( 
Color savedForeground = null; 
private static MenuElement NO_SUB ELEMENTS[] = new MenuElement[0]; 
public JToggleButtonMenultem() ( 
init(O); 
) 
public JToggleButtonMenultem(String label) ( 
super(label); 
init(O); 
J 
public JToggleButtonMenultem(String label, Icon icon) ( 
super(label, icon); 
init(O; 
y 
public JToggleButtonMenuItem(Action action) ( 
super (action); 
init(O); 
y 
private void init() ( 
updateUlI(); 
setRequestFocusEnabled(false); 
// Borrows heavily from BasicMenuUl 
MouseInputListener mouseInputListener = new MouseInputListener() ( 
// Y1f mouse released over this menu item, activate it 
public void mouseReleased(MouseEvent mouseEvent) ( 
MenuSelectionManager menuSelectionManager = 
MenuSelectionManager.defaultManager(); 
Point point = mouseEvent.getPoint(); 
if ((point.x >= 0) 88 
(point.x < getWidth()) 88 
(point.y >= 0) 88 
(point.y < getHeight())) ( 
menuSelectionManager.clearSelectedPath(); 
// Component automatically handles "selection" at this point 
// doClick(0); // not necessary 


J 
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) else £ 
menuSelectionManager.processMouseEvent (mouseEvent); 
J 
J 


// Tf mouse moves over menu item, add to selection path, so it becomes armed 
public void mouseEntered(MouseEvent mouseEvent) ( 
MenuSelectionManager menuSelectionManager = 
MenuSelectionManager.defaultManager(); 
menuSelectionManager.setSelectedPath(getPath()); 
) 
// When mouse moves away from menu item, disarm it and select something else 
public void mouseExited(MouseEvent mouseEvent) ( 
MenuSelectionManager menuSelectionManager = 
MenuSelectionManager.defaultManager(); 
MenuElement path[] = menuSelectionManager.getSelectedPath(); 
if (path.length > 1) ( 
MenuElement newPath[] = new MenuElement[path.length-1]; 
for(int i=0, c=path.length-1; i<c; i++) [ 
newPath[i] = path[i]l; 
J 
menuSelectionManager.setSelectedPath(nenPath); 
y 
) 


// Pass along drag events 


public void mouseDragged(MouseEvent mouseEvent) ( 
MenuSelectionManager.defaultManager().processMouseEvent(mouseEvent); 

) 

public void mouseClicked(MouseEvent mouseEvent) f 

J 

public void mousePressed(MouseEvent mouseEvent) f 

h 

public void mouseMoved(MouseEvent mouseEvent) f 

J 

5 


addMouseListener(mouseInputListener); 
addMouseMotionListener(mouseInputListener); 


// MenuElement methods 
public Component getComponent() ( 


) 


return this; 


public MenuElement[] getSubElements() £ 


J 


// No subelements 
return NO_SUB_ ELEMENTS; 
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public void menuSelectionChanged(boolean isIncluded) ( 
ButtonModel model = getModel(); 
// Only change armed state if different 
if(model.isArmed() != isIncluded) 4 
model .setArmed(isIncluded) ; 
) 


if (isIncluded) 4 
savedForeground = getForeground(); 
if (IsavedForeground.equals(Color.BLUE)) ( 
setForeground(Color. BLUE); 
) else £ 
// In case foreground blue, use something different 
setForeground(Color.RED); 
y 
j else [ 
setForeground(savedForeground); 
// 14 null, get foreground from installed look and feel 
if (savedForeground == null) ( 
updateUlI(); 
de 
J 
J 


public void processKeyEvent(KeyEvent keyEvent, 
MenuElement path[ ], 
MenuSelectionManager manager) 1 
// Tf user presses space while menu item armed, select it 
if (getModel().isArmed()) ( 
int keyChar = keyEvent.getKeyChar(); 
if (keyChar == KeyEvent.VK_SPACE) ( 
manager.clearSelectedPath(); 
System.out.println("Selected: JToggleButtonMenultem, by KeyEvent"); 
doClick(0); // inherited from AbstractButton 
% 
J 
J 
public void processMouseEvent(MouseEvent mouseEvent, MenuElement path[], 
MenuSelectionManager manager) ( 
// For when mouse dragged over menu and button released 
if (mouseEvent.getID() == MouseEvent.MOUSE_ RELEASED) ( 
manager.clearselectedPath(); 
System.out.println("Selected: JToggleButtonMenultem, by MouseEvent"); 
doClick(0); // inherited from AbstractButton 
J 
J 
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// Borrows heavily from BasicMenultemUI.getPath() 
private MenuElement[] getPath() ( 
MenuSelectionManager menuSelectionManager = 
MenuSelectionManager.defaultManager(); 
MenuElement oldPath[] = menuSelectionManager.getSelectedPath(); 
MenuElement newPath[ ]; 
int oldPathLength = oldPath. length; 
if (oldPathLength == 0) 
return new MenuElement[0]; 
Component parent = getParent(); 
if (oldPath[oldPathLength-1].getComponent() == parent) ( 
// Going deeper under the parent menu 
newPath = new MenuElement[oldPathLength+1]; 
System.arraycopy(oldPath, 0, newPath, 0, oldPathLength); 
newPath[oldPathLength] = this; 
j else £ 
// Sibling/child menu item currently selected 
int newPathPosition; 
for (newPathPosition = oldPath.length-1; newPathPosition >= 0; 
newPathPosition--) ( 
if (oldPath[newPathPosition].getComponent() == parent) ( 
break; 


J 


) 


newPath = new MenuElement[newPathPosition+2]; 
System.arraycopy(oldPath, 0, newPath, 0, nenPathPosition+1); 
newPath[newPathPosition+1] = this; 


J 


return newPath; 


hi 


Note The MouseInputListener defined in the init () method and the getPath() method borrow 
heavily from the system BasicMenuUI class. Normally, the user interface delegate deals with what happens 
when the mouse moves over a menu component. Because the JToggleButton isn't a predefined menu 
component, its Ul class doesn't deal with it. For better modularity, these two methods should be moved into 
an extended ToggleButtonUI. 


Once you've created this JToggleButtonMenulten class, you can use it like any other 
menu item: 


JToggleButtonMenultem toggleltem = new JToggleButtonMenultem("Balloon Help"); 
editMenu.add(toggleltem); 
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Working with Pop-Ups: The Popup Class 


Not everything you want to pop up needs to be a menu. Through the Popup and PopupFactory 
classes, you can pop up any component over another. This is different from tooltips, which are 
in a read-only, unselectable label. You can pop up selectable buttons, trees, or tables. 


Creating Pop-Up Components 


Popup is a simple class with two methods—hide() and show()—with two protected construc- 
tors. Instead of creating Popup objects directly, you acquire them from the PopupFactory class. 


PopupFactory factory = PopupFactory.getSharedInstance(); 
Popup popup = factory.getPopup(owner, contents, x, y); 


The Popup with the contents component created by PopupFactory will thus be “above” 
other components within the owner component. 


A Complete Popup/PopupFactory Usage Example 


Listing 6-7 demonstrates the usage of Popup and PopupFactory to show a JButton above another 
JButton. Selecting the initial JButton will cause the second one to be created above the first, at 
some random location. When the second button is visible, each is selectable. Selecting the initially 
visible button multiple times will cause even more pop-up buttons to appear, as shown in 
Figure 6-9. Each pop-up button will disappear after three seconds. In this example, selecting 
the pop-up button just displays a message to the console. 


Hello, World 


Hello¿ Hello, World 


Hello, World 


Hello, World f 
or Popup 


Hello, World 


Figure 6-9. Popup/PopuprFactory example 


Listing 6-7. The ButtonPopupSample Class Definition 


import java.awt.*; 
import java.awt.event.*; 
import javax.swing.*; 
import java.util.Random; 


public class ButtonPopupSample ( 
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static final Random random = new Random(); 


// Define ActionListener 
static class ButtonActionListener implements ActionListener ( 
public void actionPerformed(ActionEvent actionEvent) ( 
System.out.println("Selected: " + actionEvent.getActionCommand()); 
) 
y 


// Define Show Popup ActionListener 
static class ShowPopupActionListener implements ActionListener f 
private Component component; 
ShowPopupActionListener(Component component) ( 
this.component = component; 
J 
public synchronized void actionPerformed(ActionEvent actionEvent) ( 
JButton button = new JButton("Hello, World"); 
ActionListener listener = new ButtonActionListener(); 
button.addActionListener(listener); 
PopupFactory factory = PopupFactory.getSharedInstance(); 
int x = random.nextInt(200); 
int y = random.nextInt(200); 
final Popup popup = factory.getPopup(component, button, x, y); 
popup .show(); 
ActionListener hider = new ActionListener() ( 
public void actionPerformed(ActionEvent e) ( 
popup.hide(); 
y 
A 
// Hide popup in 3 seconds 
Timer timer = new Timer(3000, hider); 
timer.start(); 
h 
y 


public static void main(final String args[]) ( 
Runnable runner = new Runnable() 4 
public void run() £ 
// Create frame 
JFrame frame = new JFrame("Button Popup Sample"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


ActionlListener actionListener = new ShowPopupActionListener (frame); 
JButton start = new JButton("Pick Me for Popup"); 


start.addActionListener(actionListener); 
frame.add(start); 


201 


202 


CHAPTER 6 SWING MENUS AND TOOLBARS 


frame.setSize(350, 250); 
frame.setVisible(true); 
4 
5 
EventQueue.invokeLater(runner); 
J 
) 


Working with Toolbars: The JToolBar Class 


Toolbars are an integral part of the main application windows in a modern user interface. 
Toolbars provide users with easy access to the more commonly used commands, which are 
usually buried within a hierarchical menuing structure. The Swing component that supports 
this capability is the JToo1Bar. 

The JToo1Baris a specialized Swing container for holding components. This container can 
then be used as a toolbar within your Java applet or application, with the potential for it to 
be floating or draggable, outside the main window of the program. JToo1Bar is a very simple 
component to use and understand. 


Creating JToolBar Components 
There are four constructors for creating JToo1Bar components: 
public JToolBar() 


JToolBar jToolBar = new JTool1Bar(); 


public JToolBar(int orientation) 
JToolBar jToolBar = new JTool1Bar(JToolBar.VERTICAL); 


public JTool1Bar(String name) 
JToolBar jToolBar = new JToolBar("Window Title"); 


public JTool1Bar(String name,int orientation) 
JToolBar jToolBar = new JToolBar("Window Title", ToolBar.VERTICAL); 


By default, a toolbaris created in a horizontal direction. However, you can explicitly setthe 
orientation by using either of the JToo1Bar constants of HORIZONTAL and VERTICAL. 

Also by default, toolbars are floatable. Therefore, if you create the toolbar with one orien- 
tation, the user could change its orientation while dragging the toolbar around outside the 
window. When floating, the title will be visible on the toolbar's frame. 


Adding Components to a JToolBar 


Once you have a JToo1Bar, you need to add components to it. Any Component can be added to 
the toolbar. When dealing with horizontal toolbars, for aesthetic reasons, it's best ifthe toolbar 
components are all roughly the same height. For a vertical toolbar, it's best if they're roughly 
the same width. There's only one method defined by the JToo1Bar class for adding toolbar 
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items; the remaining methods, such as add(Component), are inherited from Container. In addition, 
you can add a separator to a toolbar. 


public JButton add(Action action); 
public void addSeparator(); 
public void addSeparator(Dimension size); 


When using the add(Action) method of JToo1Bar, the added Action is encapsulated within 
a JButton object. This is different from adding actions to JMenu or JPopupMenu components, in 
which JMenultem objects are added instead. As with JMenu and JPopupMenu, adding an Action in 
this fashion is discouraged in the Javadoc for the class. For separators, if you don't specify the 
size, the installed look and feel forces a default size setting. 


Note For more information about dealing with the Action interface, see Chapter 2 or the section “Using 
Action Objects with Menus” earlier in this chapter. 


To remove components from a toolbar, use the following method: 


public void remove(Component component) 


JToolBar Properties 


The JToo1Bar class defines nine properties, which are listed in Table 6-15. 


Table 6-15. JToolBar Properties 


Property Name Data Type Access 
accessibleContext AccessibleContext Read-only 
borderPainted boolean Read-write bound 
floatable boolean Read-write bound 
layout LayoutManager Write-only 

margin Insets Read-write bound 
orientation int Read-write bound 
rollover boolean Read-write bound 
UI Tool1BarUI Read-write 
UlClassID String Read-only 


By default, the border of a JToo1Bar is painted. If you don't want the border painted, you 
can set the borderPainted property to false. Without using the borderPainted property, 
you would need to change the setting of the border property (inherited from the superclass 
JComponent). 
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The orientation property can be set to only one ofthe HORIZONTAL or VERTICAL constants 
of JToo1Bar. If another nonequivalent value is used, an I11egalArgumentException is thrown. 
Changing the orientation changes the layout manager of the toolbar. Ifyou directly change the 
layout manager with setLayout (), changing the orientation will undo your layout change. 


Consequently, it's best not to manually change the layout manager of a JToo1Bar. 


As previously mentioned, a toolbar is floatable by default. This means that a user can drag 
the toolbar from where you place it and move it elsewhere. To drag a toolbar, the user selects 
an empty part of it. The toolbar can than be left outside the original program window, floating 


above the main window in its own window, or dropped onto another area of the original 


program window. Ifthe layout manager ofthe original windowis BorderLayout, the droppable 
areas are the edges of the layout manager without any components. (You can't drop the toolbar 
in the center ofthe window.) Otherwise, the toolbar would be dropped into the last spot of the 


container. Figure 6-10 shows the different phases of the dragging and docking process. 


Dragging Hot Spot 


£ JToolBar Example - 101 xf 


0 0 9 mou 


Floating 


9... 


About 
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import java.awt.event*; 
import javax.swing.*; 


public class ToolBarsample ( 
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private static final int STRING_POSITION = 1; 
static Object buttonColors[][] = ( 

(Color.RED, "RED"), 

(Color.BLUE, "BLUE"), 
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Docked in a Different Area 


Figure 6-10. JToolBar phases 


Undocked Floating Toolbar 
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The rol1lover property defines a behavior specific to the look and feel for when the user 
moves the mouse over the different components within the toolbar. This behavior could 
involve coloration or border differences. 


Handling JToolBar Events 


There are no events specific to the JToo1Bar. You need to attach listeners to each item on the 
JToo1Bar that you want to respond to user interaction. Of course, JToo1Bar is a Container, so 
you could listen to its events. 


Customizing a JToolBar Look and Feel 


Each installable Swing look and feel provides its own JToo1Bar appearance and set of default 
UTResource values. Most of this appearance is controlled by the components actually within 
the toolbar. Figure 6-11 shows the appearance ofthe JToo1Bar component for the preinstalled 
set of look and feel types: Motif, Windows, and Ocean. Each toolbar has five JButton compo- 
nents, with a separator between the fourth and fifth. 


sa lali 
+4. + .. + 


Motif Windows 
10 xi 
9. e 


Ocean 


Figure 6-11. JToolBar under different look and feel types 


The available set ofUTResource-related properties for a JToo1Bar is shown in Table 6-16. 
For the JToolBar component, there are 22 different properties. 


Table 6-16. JToolBar UlResource Elements 


Property String Object Type 
ToolBar.actionMap ActionMap 
ToolBar.ancestorInputMap InputMap 


ToolBar.background Color 
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Table 6-16. JToolBar UlResource Elements (Continued) 


Property String Object Type 
ToolBar.border Border 
ToolBar.borderColor Color 
ToolBar.darkShadow Color 
ToolBar.dockingBackground Color 
ToolBar.dockingForeground Color 
ToolBar.floatingBackground Color 
ToolBar.floatingForeground Color 
ToolBar.font Font 
ToolBar.foreground Color 
ToolBar.handleIcon Icon 
ToolBar.highlight Color 
ToolBar.isRollover Boolean 
ToolBar.light Color 
ToolBar.nonrolloverBorder Border 
ToolBar.rolloverBorder Border 
ToolBar.separatorSize Dimension 
Tool1Bar. shadow Color 
ToolBarSeparatoruI String 
Tool1Barul String 


A Complete JToolBar Usage Example 


The program in Listing 6-8 demonstrates a complete JToo1Bar example that results in a toolbar 
with a series of diamonds on the buttons. The program also reuses the ShowAction defined for 
the menuing example, presented in Listing 6-2 earlier in this chapter. 

The rollover property is enabled to demonstrate the difference for the current look and 
feel. See Figure 6-12 for the output as you move your mouse over the different buttons. 


lola 
+. 4% "about 


Figure 6-12. JToolBar example with isRollover enabled 
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Listing 6-8. The ToolBarSample Class Definition 


import java.awt.*; 
import java.awt.event.*; 
import javax.swing.*; 


public class ToolBarSample ( 


private static final int COLOR POSITION = 0; 
private static final int STRING POSITION = 1; 
static Object buttonColors[][] = £ 

[Color.RED, "RED"), 

[Color.BLUE, "BLUE”), 

[Color.GREEN, "GREEN"), 

[Color.BLACK, "BLACK"), 

null, // separator 

[Color.CYAN, "CYAN") 
_5 


public static class TheActionListener implements ActionListener ( 
public void actionPerformed (ActionEvent actionEvent) ( 
System.out.println(actionEvent.getActionCommand()); 
J 
5 


public static void main(final String args[]) ( 


Runnable runner = new Runnable() £ 
public void run() £ 


JFrame frame = new JFrame("JToolBar Example"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
ActionListener actionListener = new TheActionListener(); 


JToolBar toolbar = new JToolBar(); 
toolbar.setRollover(true); 


for (Object[] color: buttonColors) f 

if (color == null) ( 
toolbar.addSeparator(); 

y else [ 
Icon icon = new DiamondIcon((Color)color[COLOR POSITION], true, 20, 20); 
JButton button = new JButton(icon); 
button.setActionCommand((String)color[STRING_POSITION]); 
button.addActionListener(actionListener); 
toolbar.add(button); 
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Action action = new ShowAction(frame); 
JButton button = new JButton(action); 
toolbar.add(button); 


Container contentPane = frame.getContentPane(); 
contentPane.add(toolbar, BorderLayout.NORTH); 
JTextArea textArea = new JTextArea(); 
JScrollPane pane = new JScrollPane(textArea); 
contentPane.add(pane, BorderLayout.CENTER); 
frame.setSize(350, 150); 
frame.setVisible(true); 
y 
E 
EventQueue.invokeLater(runner); 
J 
) 


JToolBar.Separator Class 


The JToo1Bar class maintains its own separator to permit a custom look and feel for the 
separator when on a JTool1Bar. 

This separator is automatically created when you call the addSeparator() method of 
JToo1Bar. In addition, there are two constructors for creating a JToo1Bar.Separator if you 
want to manually create the component. 


public JToolBar.Separator() 
JSeparator toolBarSeparator = new JToolBar.Separator(); 


public JToolBar.Separator(Dimension size) 
Dimension dimension = new Dimension(10, 10); 
JSeparator toolBarSeparator = new JToo1Bar.Separator(dimension); 


Both constructors create a horizontal separator. You can configure the size. If you don't 
specify this, the look and feel decides what size to make the separator. 

As with JPopupMenu.Separator, if you want to change the orientation of the separator, you 
must call the set0rientation() method inherited from JSeparator, this time with an argument 
of JToo1Bar.Separator.VERTICAL. 


Summary 


This chapter introduced the many Swing menu-related classes and their interrelationships, 
and Swing's toolbar class. First, you learned about the JMenuBar and its selection model, and 
learned how menu bars can be used within applets as well as applications. 

Next, you explored the JMenuTtem, which is the menu element the user selects, along with two 
new event/listener pairs the system uses for dealing with events, MenuKeyEvent /MenuKeyListener 
and MenuDragMouseEvent/MenuDragMouseListener. Then, you moved on to the JMenu compo- 
nent, upon which JMenultem instances are placed, along with its new event/listener pair, 
MenuEvent/MenuListener, which is used to determine when a menu is about to be posted. 
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Next, you learned about the JSeparator component and how you can use it as a menu 
separator or as a visual display separator outside of menus. 

You then explored the JPopupMenu, which JMenu uses to display its set of MenuItem compo- 
nents. For the JPopupMenu, you learned about the pop-up menu's own event/listener pair, 
PopupMenuEvent/PopupMenuListener. 

Then the selectable menu elements in JCheckBoxMenuTtem and JRadioButtonMenuTtem were 
explored with their MenuElement interface, and you saw howto create a custom menu component. 

Menus aren't the only things that might pop up, so you explored Popup and PopupFactory. 
Finally, the chapter covered the JToo1Bar class, a close cousin of Swing's menu classes. 

In Chapter 7, you'1l look at the different classes Swing provides for customizing the border 
around a Swing component. 
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Borders 


Sins components offer the option of customizing the border area surrounding that component. 
With great ease, you can use any one ofthe eight predefined borders (including one compound 
border thatis a combination of any of the other seven), or you can create your own individual- 
ized borders. In this chapter, you'll learn how to best use each of the existing borders and how 
to fashion your own. 


Some Basics on Working with Borders 


A border is a JComponent property with the standard setBorder() and getBorder() property 
methods. Therefore, every Swing component that is a subclass of JComponent can have a border. 
By default, a component doesn't have a custom border associated with it. (The getBorder() 
method of JComponent returns null.) Instead, the default border displayed for a component is 
the border appropriate for its state, based on the current look and feel. For instance, with a 
JButton, the border could appear pressed, unpressed, or disabled, with specific different borders 
for each look and feel (Metal, Windows, and so on). 

Although the initial border property setting for every component is null, you can change 
the border of a component by calling the setBorder(Border newValue) method of JComponent. 
Once set, the changed value overrides the border for the current look and feel, and it draws the 
new border in the area ofthe component's insets. Ifat a later time, you want to reset the border 
back to a border that's appropriate for the state as well as the look and feel, change the border 
property to null, using setBorder(nul1), and call updateUI() for the component. The updateUI (>) 
call notifies the look and feel to reset the border. If you don't call updateUI (), the component 
will have no border. 


Note Those Swing components that aren't subclasses of JComponent, such as JApplet and JFrame, 
lack a setBorder () method to change their border. If you want them to have a border, you must add a 
JPanel or other Swing component to the container, and then change the border of that component. 
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Examine Figure 7-1 to see a sampling of the various border configurations around a JLabel, 
with a text label designatingthe border type. Howto create the different borders will be discussed 
in later sections of this chapter. 


lol 
Bevel Empty Line 


Figure 7-1. Border examples, using a 4-by-2 GridLayout with 5-pixel horizontal and vertical gaps 


Exploring the Border Interface 


The Border interface can be found in the javax. swing. border package. This interface forms the 
basis of all the border classes. The interface is directly implemented by the AbstractBorder 
class, which is the parent class of all the predefined Swing border classes: BevelBorder, 
CompoundBorder, EmptyBorder, EtchedBorder, LineBorder, MatteBorder, SoftBevelBorder, and 
TitledBorder. Of additional interest is the BorderFactory class, found in the javax.swing 
package. This class uses the Factory design pattern to create borders, hiding the details of the 
concrete implementations and caching various operations to optimize shared usages. 

The Border interface shown here consists of three methods: paintBorder(), 
getBorderInsets(), and isBorder0paque(). These methods are described in the following 
sections. 


paintBorder() 


The paintBorder() method is the key method of the interface. It has the following definition: 


public void paintBorder(Component c, Graphics g, int x, int y, int 
width, int height) 


The actual drawing of the border is done in this method. Frequently, the Border imple- 
mentation will ask for the Insets dimensions first, and then draw the border in the four 
rectangular outer regions, as shown in Figure 7-2. Ifa border is opaque, the paintBorder() 
implementation must fill the entire insets area. If a border is opaque and doesn't fill the area, 
then it's a bug and needs to be corrected. 
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Figure 7-2. Areas of border insets 


Listing 7-1 shows a simple paintBorder() implementation that fills in the left and right 


sides with a brighter color than the top and bottom. 


Listing 7-1. Filled-in Border Inset Areas 


public void paintBorder(Component c, Graphics g, int x, int y, int width, 
int height) ( 
Insets insets = getBorderInsets(c); 
Color color = c.getForeground(); 
Color brighterColor = color.brighter(); 


// Translate coordinate space 
g.translate(x, y); 


// Top 
g.setColor(color); 
g.fillRect(0, O, width, insets.top); 


// Left 
g.setColor(brighterColor); 
g.fillRect(0, insets.top, insets.left, height-insets.top-insets.bottom); 


// Bottom 
g.setColor(color); 
g.fillRect(0, height-insets.bottom, width, insets.bottom); 
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// Right 
g.setColor(brighterColor); 
g-FillRect(width-insets.right, insets.top, insets.right, 
height-insets.top-insets.bottom); 


// Translate coordinate space back 
g-translate(-x, -y); 


When creating your own borders, you'll frequently find yourself filling in the same nonover- 
lapping rectangular regions. The use of the translate() method of Graphics simplifies the 
specification ofthe drawing coordinates. Without translating the coordinates, you would need 
to offset the drawing by the origin (x, y). 


Caution You cannot take a shortcut by inserting g. FillRect(x, y, width, height), because this 
would fill in the entire component area, not just the border area. 


getBorderlnsets() 


The getBorderInsets () method returns the space necessary to draw a border around the given 
component c as an Insets object. It has the following definition: 


public Insets getBorderInsets(Component c) 


These inset areas, shown in Figure 7-2, define the only legal area in which a border can be 
drawn. The Component argument allows you to use some ofits properties to determine the size 
of the insets area. 


Caution You can ask the component argument for font-sizing information to determine the insets' size, 
but if you ask about the size of the component, a StackOverflowError occurs because the size of the 
component is dependent on the size of the border insets. 


isBorderOpaque() 


Borders can be opaque or transparent. The isBorder0paque() method returns true or false, to 
indicate which form the border is. It has the following definition: 


public boolean isBorderOpaque() 
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When this method returns true, the border needs to be opaque, filling its entire insets 
area. When it returns false, any area not drawn will retain the background of the component 
in which the border is installed. 


Introducing BorderFactory 


Now that you have a basic understanding of how the Border interface works, let's take a quick 
look at the BorderFactory class as a means to create borders swiftly and easily. Found in the 
javax.swing package, the BorderFactory class offers a series of static methods for creating 
predefined borders. Instead of laboriously calling the specific constructors for different borders, 
you can create almost all the borders through this factory class. The factory class also caches 
the creation of some borders to avoid re-creating commonly used borders multiple times. The 
class definition follows. 


public class BorderFactory ( 

public static Border createBevelBorder(int type); 

public static Border createBevelBorder(int type, Color highlight, 
Color shadow) ; 
public static Border createBevelBorder(int type, Color highlight0uter, 
Color highlightInner, Color shadow0uter, Color shadowInner); 


public static CompoundBorder createCompoundBorder(); 
public static CompoundBorder createCompoundBorder(Border outside, 
Border inside); 


public static Border createEmptyBorder(); 
public static Border createEmptyBorder(int top, int left, int bottom, 
int right); 


public static Border createEtchedBorder(); 

public static Border createEtchedBorder(Color highlight, Color shadow); 
public static Border createEtchedBorder(int type); 

public static Border createEtchedBorder(int type, Color highlight, 


Color shadow) ; 


public static Border createlineBorder(Color color); 
public static Border createlineBorder(Color color, int thickness); 


public static Border createLoweredBevelBorder(); 


public static MatteBorder createMatteBorder(int top, int left, int bottom, 

int right, Color color); 

public static MatteBorder createMatteBorder(int top, int left, int bottom, 
int right, Icon icon); 
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public static Border createRaisedBevelBorder(); 


public static TitledBorder createTitledBorder(Border border); 

public static TitledBorder createTitledBorder(Border border, String title); 
public static TitledBorder createTitledBorder(Border border, String title, 
int justification, int position); 

public static TitledBorder createTitledBorder(Border border, String title, 
int justification, int position, Font font); 

public static TitledBorder createTitledBorder(Border border, String title, 
int justification, int position, Font font, Color color); 

public static TitledBorder createTitledBorder(String title); 


P'll describe the different methods ofthis class during the process of describing the specific 
border types they create. For instance, to create a border with a red line, you can use the following 
statement, and then attach the border to a component. 


Border lineBorder = BorderFactory.createLineBorder(Color.RED); 


Note Interestingly enough, no factory method exists for creating a SoftBevelBorder. 


Starting with AbstractBorder 


Before looking at the individual borders available within the javax.swing.border package, 
one system border deserves special attention: AbstractBorder. As previously mentioned, the 
AbstractBorder class is the parent border of all the other predefined borders. 


Tip When creating your ovn borders, you should create a subclass of AbstractBorder and just override 
the necessary methods, instead of implementing the Border interface directly yourself. There are some 
internal optimizations in place for subclasses. 


Creating Abstract Borders 
There is one constructor for AbstractBorder: 
public AbstractBorder() 


Because AbstractBorder is the parent class of all the other standard borders, this constructoris 
eventually called automatically for all of them. 
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Note Borders are not meant to be used as JavaBean components. Some border classes even lack a 
no-argument (“no-arg” for short) constructor. Nevertheless, those border classes still call this constructor. 


Examining AbstractBorder Methods 


The AbstractBorder class provides implementations for the three methods of the Border 
interface. 


public Insets getBorderInsets(Component c) 


The insets of an AbstractBorder are zero all around. Each of the predefined subclasses 
overrides the getBorderInsets() method. 


public boolean isBorderO0paque() 


The default opaque property setting of an abstract border is false. This means that if you 
were to draw something like dashed lines, the component background would show through. 
Many predefined subclasses override the isBorder0paque() method. 


public void paintBorder(Component c, Graphics g, int x, int y, 
int width, int height) 


The painted border for an AbstractBorder is empty. All subclasses should override this 
behavior to actually draw a border, except perhaps EmptyBorder. 

In addition to providing default implementations of the Border methods, AbstractBorder 
adds two other capabilities that you can take advantage of, or just let the system use. First, 
there's an additional version of getBorderInsets() available that takes two arguments: 
Component and Insets: 


public Insets getBorderInsets(Component c, Insets insets) 


In this version of the method, instead of creating and returning a new Insets object, the 
Insets object passed in is first modified and then returned. Use of this method avoids the creation 
and later destruction of an additional Insets object each time the border insets is queried. 

The second new method available is getInteriorRectangle(), which has both a static and 
a nonstatic version. Given the Component, Border, and four integer parameters (for x, y, width, 
and height), the method will return the inner Rectangle such that a component can paint itself 
only in the area within the border insets. (See the piece labeled “Component” in Figure 7-2, 
shown earlier in the chapter.) 


Note Currently, getBorderTnsets() is used only once in Sun's Swing source. That place is the 
MotifButtonUI class found in the com.sun.java.swing.plaf.motif package. 
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Examining the Predefined Borders 


Now that the basics have been described, let's look at the specifics of each of the predefined 
border classes, somewhat in order of complexity. 


EmptyBorder Class 


The empty border, logically enough, is a border with nothing drawn in it. You can use 
EmptyBorder where you might have otherwise overridden insets() or getInsets() with a 
regular AWT container. It allows you to reserve extra space around a component to spread your 
screen components out a little orto alter centering or justification somewhat. Figure 7-3 shows 
both an empty border and one that is not empty. 


BENTOS lo 


With Empty 
Without Empty 


Figure 7-3. EmptyBorder sample, with insets of 20 for top and left, O for right and bottom 


EmptyBorder has two constructors and two factory methods of BorderFactory: 


public static Border createEmptyBorder() 
Border emptyBorder = BorderFactory.createEmptyBorder(); 


public static Border createEmptyBorder(int top, int left, int bottom, int right) 
Border emptyBorder = BorderFactory.createEmptyBorder(5, 10, 5, 10); 


public EmptyBorder(Insets insets) 
Insets insets = new Insets(5, 10, 5, 10); 
Border EmptyBorder = new EmptyBorder(insets); 


public EmptyBorder(int top, int left, int bottom, int right) 
Border EmptyBorder = new EmptyBorder(5, 10, 5, 10); 


Each allows you to customize the border insets in its own manner. The no-argument 
version creates a truly empty border with zero insets all around; otherwise, you can specify the 
insets as either an AWT Insets instance or as the inset pieces. The EmptyBorder is transparent 
by default. 
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Note When creating an empty border, with zeros all around, you should use the factory method to create 
the border, avoiding the direct constructors. This allows the factory to create one truly empty border to be 
shared by all. If all you want to do is hide the border, and the component is an AbstractButton subclass, 
just call setBorderPainted(false). 


LineBorder Class 


The line border is a single-color line of a user-defined thickness that surrounds a component. 
It can have squared-off or rounded corners. Ifyou want to alter the thickness on different sides, 
you'll need to use MatteBorder, which is described in the section “Matte Border Class” later in 
this chapter. Figure 7-4 shows a sampling of using LineBorder, with 1- and 12-pixel line thick- 
nesses, with and without rounded corners. 


ala 


12 Pixel 


Rounded 12 Pixel 


Figure 7-4. LineBorder sample 


Creating Line Borders 


The LineBorder class has three constructors, two factory methods within it, and two factory 
methods of BorderFactory: 


public LineBorder(Color color) 
Border lineBorder = new LineBorder (Color.RED); 


public LineBorder(Color color, int thickness) 
Border lineBorder = new LineBorder (Color.RED, 5); 


public LineBorder (Color color, int thickness, boolean roundedCorners) 
Border lineBorder = new LineBorder (Color.RED, 5, true); 


public static Border createBlackLineBorder() 
Border blackLine = LineBorder.createBlackLineBorder(); 
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public static Border createGrayLineBorder() 
Border graylLine = LineBorder.createGrayLineBorder(); 


public static Border createLineBorder(Color color) 
Border lineBorder = BorderFactory.createLineBorder(Color.RED); 


public static Border createLineBorder(Color color, int thickness) 
Border lineBorder = BorderFactory.createLineBorder(Color.RED, 5); 


Note The LineBorder factory methods work as follows: If you create the same border twice, the same 
LineBorder object will be returned. However, as with all object comparisons, you should always use the 
equals () method for checking object equality. 


Each allows you to customize the border color and line thickness. If a thickness isn't spec- 
ified, a default value of 1 is used. The two factory methods of LineBorder are for the commonly 
used colors of black and gray. Because the border fills in the entire insets area, the LineBorder 
is opaque, unless there are rounded corners. So, the opacity of the border is the opposite ofthe 
rounded-corner setting. 


Configuring Line Border Properties 


Table 7-1 lists the inherited border0paque property from AbstractBorder and the immutable 
properties of LineBorder. 


Table 7-1. LineBorder Properties 


Property Name Data Type Access 
borderO0paque boolean Read-only 
lineColor Color Read-only 
roundedCorners boolean Read-only 
thickness int Read-only 
BevelBorder Class 


A bevel border draws a border with a three-dimensional appearance, which can appear to be 
raised or lowered. When the border is raised, a shadow effect appears along the bottom and 
right side of the border. When lowered, the position of the shading is reversed. Figure 7-5 
shows raised and lowered bevel borders with default and custom colors. 
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Figure 7-5. Raised and lowered BevelBorder sample 


Drawing two different pairs of 1-pixel-wide lines around the component produces a simu- 
lated three-dimensional appearance. The border sides that aren't shaded are drawn with what 
is called a highlight color, and the other two sides are drawn with a shadow color. The highlight 
color and shadow color are each drawn in two different shades for the outer and inner edges of 
the bevel. As such, a drawn bevel border uses four different colors in all. Figure 7-6 shows how 
these four colors fit together. 


Light 
Source 


Outer Highlight Color Outer Shadow Color 


Raised Component 


Qimer Highlight Color Inner Shadow color] 


Figure 7-6. Bevel color analysis 


There are three constructors and one factory method of BevelBorder, as well as five factory 
methods by which BorderFactory creates BevelBorder objects: 


public BevelBorder(int bevelType) 
Border bevelBorder = new BevelBorder(BevelBorder.RAISED); 


public static Border createBevelBorder(int bevelType) 
Border bevelBorder = BorderFactory.createBevelBorder(BevelBorder.RAISED); 


public static Border createLoweredBevelBorder (>) 
Border bevelBorder = BorderFactory.createLoweredBevelBorder(); 
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public static Border createRaisedBevelBorder() 
Border bevelBorder = BorderFactory.createRaisedBevelBorder(); 


public BevelBorder(int bevelType, Color highlight, Color shadow) 
Border bevelBorder = new BevelBorder(BevelBorder.RAISED, Color.PINK, Color.RED); 


public static Border createBevelBorder(int bevelType, Color highlight, Color shadow) 
Border bevelBorder = BorderFactory.createBevelBorder(BevelBorder.RAISED, 
Color.PINK, Color.RED); 


public BevelBorder(int bevelType, Color highlight0uter, Color highlightInner, 
Color shadow0uter, Color shadowInner) 

Border bevelBorder = new BevelBorder(BevelBorder.RAISED, Color.PINK, 
Color.PINK.brighter(), Color.RED, Color.RED.darker()); 


public static Border createBevelBorder(int bevelType, Color highlight0uter, 
Color highlightInner, Color shadow0uter, Color shadowInner) 

Border bevelBorder = BorderFactory.createBevelBorder(BevelBorder.RAISED, 
Color.PINK, Color.PINK.brighter(), Color.RED, Color.RED.darker()); 


Each allows you to customize both the bevel type and the coloration of the highlighting 
and shadowing within the border. The bevel type is specified by one of two values: 
BevelBorder.RAISED or BevelBorder. LOWERED. If highlight and shadow colors aren't specified, 
the appropriate colors are generated by examining the background of the component for the 
border. If you do specify them, remember that the highlight color should be brighter, possibly 
done by calling theColor.brighter(). A BevelBorder is opaque, by default. 


SoftBevelBorder Class 


The soft bevel border is a close cousin of the bevel border. It rounds out the corners so that 
their edges aren't as sharp, and it draws only one line, using the appropriate outer color for the 
bottom and right sides. As Figure 7-7 shows, the basic appearance of the raised and lowered 
SoftBevelBorder is roughly the same as that of the BevelBorder. 


£ Soft Bevel Borders 10 / xÍ 
Raised Lowered 


Figure 7-7. Raised and lowered SoftBevelBorder sample 
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SoftBevelBorder has three constructors: 


public SoftBevelBorder(int bevelType) 
Border softBevelBorder = new SoftBevelBorder(SoftBevelBorder.RAISED); 


public SoftBevelBorder(int bevelType, Color highlight, Color shadow) 
Border softBevelBorder = new SoftBevelBorder(SoftBevelBorder.RAISED, Color.RED, 
Color .PINK); 


public SoftBevelBorder(int bevelType, Color highlight0uter, Color highlightInner, 
Color shadow0uter, Color shadowInner) 

Border softBevelBorder = new SoftBevelBorder(SoftBevelBorder.RAISED, Color.RED, 
Color.RED.darker(), Color.PINK, Color.PINK.brighter()); 


Each allows you to customize both the bevel type and the coloration of the highlighting 
and shadowing within the border. The bevel type is specified by one of two values: 
SoftBevelBorder.RAISED or SoftBevelBorder . LONERED. As with BevelBorder, the default colora- 
tion is derived from the background color. A soft bevel border doesn't completely fill in the 
given insets area, so a SoftBevelBorder is created to be transparent (not opaque). 

There are no static BorderFactory methods to create these borders. 


EtchedBorder Class 


An EtchedBorder is a special case of a BevelBorder, but it's not a subclass. When the outer high- 
light color of a BevelBorder is the same color as the inner shadow color and the outer shadow 
color is the same color as the inner highlight color, you have an EtchedBorder. (See Figure 7-6 
earlier in this chapter for a depiction of bevel colors.) Figure 7-8 shows what a raised and 
lowered etched border might look like. 


lol 
Raised Lowered 


Figure 7-8. EtchedBorder samples 


There are four constructors for EtchedBorder, as well as four factory methods of 
BorderFactory for creating EtchedBorder objects: 
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public EtchedBorder(>) 
Border etchedBorder = new EtchedBorder(); 


public EtchedBorder(int etchType) 
Border etchedBorder = new EtchedBorder(EtchedBorder.RAISED); 


public EtchedBorder(Color highlight, Color shadow) 
Border etchedBorder = new EtchedBorder(Color.RED, Color.PINK); 


public EtchedBorder(int etchType, Color highlight, Color shadow) 
Border etchedBorder = new EtchedBorder(EtchedBorder.RAISED, Color.RED, 
Color. PINK); 


public static Border createEtchedBorder() 
Border etchedBorder = BorderFactory.createEtchedBorder(); 


public static Border createEtchedBorder(Color highlight, Color shadow) 
Border etchedBorder = BorderFactory.createEtchedBorder(Color.RED, Color.PINK); 


public static Border createEtchedBorder(EtchedBorder.RAISED) 
Border etchedBorder = BorderFactory.createEtchedBorder(Color.RED, Color.PINK); 


public static Border createEtchedBorder(int type, Color highlight, Color shadow) 
Border etchedBorder = BorderFactory.createEtchedBorder(EtchedBorder.RAISED, 
Color.RED, Color.PINK); 


Each allows you to customize both the etching type and the coloration of the highlighting 
and shadowing within the border. If no etching type is specified, the border is lowered. As with 
BevelBorder and SoftBevelBorder, you can specify the etching type through one of two constants: 
EtchedBorder .RAISED or EtchedBorder. LONERED. Again, if no colors are specified, they're derived 
from the background color of the component passed into paintBorder(). By default, all 
EtchedBorder objects are created to be opaque. 


MatteBorder Class 


MatteBorder is one of the more versatile borders available. It comes in two varieties. The first is 
demonstrated in Figure 7-9 and shows a MatteBorder used like a LineBorder to fill the border 
with a specific color, but with a different thickness on each side (something a plain LineBorder 
cannot handle). 
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Figure 7-9. MatteBorder color sample 


The second variety uses an Icon tiled throughout the border area. This Icon could be an 
Imagelcon, if created from an Image object, or it could be one you create yourself by imple- 
menting the Icon interface. Figure 7-10 demonstrates both implementations. 
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Figure 7-10. MatteBorder icon samples 


Tip When tiling an icon, the right and bottom areas may not look very attractive if the border size, 
component size, and icon size fail to mesh well. 


There are seven constructors and two factory methods of BorderFactory for creating 
MatteBorder objects: 


public MatteBorder(int top, int left, int bottom, int right, Color color) 
Border matteBorder = new MatteBorder(5, 10, 5, 10, Color.GREEN); 


public MatteBorder(int top, int left, int bottom, int right, Icon icon) 
Icon diamondIcon = new DiamondIcon(Color.RED); 
Border matteBorder = new MatteBorder(5, 10, 5, 10, diamondIcon); 


public MatteBorder(Icon icon) 
Icon diamondIcon = new DiamondIcon(Color.RED); 
Border matteBorder = new MatteBorder(diamondIcon); 
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public MatteBorder(Insets insets, Color color) 
Insets insets = new Insets(5, 10, 5, 10); 
Border matteBorder = new MatteBorder(insets, Color.RED); 


public MatteBorder(Insets insets, Icon icon) 

Insets insets = new Insets(5, 10, 5, 10); 

Icon diamondIcon = new DiamondIcon(Color.RED); 

Border matteBorder = new MatteBorder(insets, diamondIcon); 


public static MatteBorder createMatteBorder(int top, int left, int bottom, 
int right, Color color) 
Border matteBorder = BorderFactory.createMatteBorder(5, 10, 5, 10, Color.GREEN); 


public static MatteBorder createMatteBorder(int top, int left, int bottom, 
int right, Icon icon) 
Icon diamondIcon = new DiamondIcon(Color.RED); 
Border matteBorder = BorderFactory.createMatteBorder(5, 10, 5, 10, diamondIcon); 


Each allows you to customize what will be matted within the border area. When tiling an 
Icon, if you don't specify the border insets size, the actual icon dimensions will be used. 


CompoundBorder Class 


After EmptyBorder, the compound border is probably one ofthe simplest predefined borders to 
use. It takes two existing borders and combines them, using the Composite design pattern, into 
asingle border. A Swing component can have only one border associated with it, therefore, the 
CompoundBorder allows you to combine borders before associating them with a component. 

Figure 7-11 shows two examples of CompoundBorder in action. The border on the leftis a beveled, 
line border. The one on the right is a six-line border, with several borders combined together. 


[2 Compound vorders AE 


Figure 7-11. CompoundBorder samples 


Creating Compound Borders 


There are two constructors for CompoundBorder and two factory methods that BorderFactory 
offers for creating CompoundBorder objects (the no-argument constructor and factory methods 
are completely useless here, because there are no setter methods to later change the compounded 
borders, so no source examples are shown for them): 
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public CompoundBorder(>) 


public static CompoundBorder createCompoundBorder() 


public CompoundBorder(Border outside, Border inside) 
Border compoundBorder = new CompoundBorder(lineBorder, matteBorder); 


public static CompoundBorder createCompoundBorder(Border outside, Border inside) 
Border compoundBorder = BorderFactory.createCompoundBorder(lineBorder, 
matteBorder); 


Tip Keep in mind that CompoundBorder is itself a Border, so you can combine multiple borders into one 
border many levels deep. 


The opacity of a compound border depends on the opacity of the contained borders. 
If both contained borders are opaque, so is the compound border. Otherwise, a compound 
border is considered transparent. 


Configuring Properties 


In addition to the border0paque property inherited from AbstractBorder, Table 7-2 lists the two 
read-only properties CompoundBorder adds. 


Table 7-2. CompoundBorder Properties 


Property Name Data Type Access 
border0paque boolean Read-only 
insideBorder Border Read-only 
outsideBorder Border Read-only 
TitledBorder Class 


Probably the most interesting border, TitledBorder can also be the most complicated to use. The 
titled border allows you to place a text string around a component. In addition to surrounding a 
single component, you can place a titled border around a group of components, like JRadioButton 
objects, as long as they're placed within a container such as a JPanel. The TitledBorder can be 
difficult to use, but there are several ways to simplify its usage. Figure 7-12 shows both a simple 
titled border and one that's a little more complex. 
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Figure 7-12. TitledBorder samples 


Creating Titled Borders 


Six constructors and six BorderFactory factory methods exist for creating TitledBorder objects. 
Each allows you to customize the text, position, and appearance of a title within a specified 
border. When unspecified, the current look and feel controls the border, title color, and title 
font. The default location for the title is the upper-left corner, while the default title is the 
empty string. A titled border is always at least partially transparent because the area beneath 
the title text shows through. Therefore, isBorder0paque() reports false. 

If you look at each of the following methods, shown in pairs, this will be easier to understand. 
First shown is the constructor method; next shown is the equivalent BorderFactory method. 


public TitledBorder(Border border) 
Border titledBorder = new TitledBorder(lineBorder); 


public static TitledBorder createTitledBorder(Border border) 
Border titledBorder = BorderFactory.createTitledBorder(lineBorder); 


public TitledBorder(String title) 
Border titledBorder = new TitledBorder("Hello"); 


public static TitledBorder createTitledBorder(String title) 
Border titledBorder = BorderFactory.createTitledBorder("Hello"); 


public TitledBorder(Border border, String title) 
Border titledBorder = new TitledBorder(lineBorder, "Hello"); 


public static TitledBorder createTitledBorder(Border border, String title) 
Border titledBorder = BorderFactory.createTitledBorder(lineBorder, "Hello"); 


public TitledBorder(Border border, String title, int justification, int position) 
Border titledBorder = new TitledBorder(lineBorder, "Hello", TitledBorder.LEFT, 
TitledBorder.BELOW_ BOTTOM); 
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public static TitledBorder createTitledBorder(Border border, String title, 
int justification, int position) 

Border titledBorder = BorderFactory.createTitledBorder(lineBorder, "Hello", 
TitledBorder.LEFT, TitledBorder.BELOW_ BOTTOM); 


public TitledBorder(Border border, String title, int justification, int position, 
Font font) 

Font font = new Font("Serif", Font.ITALIC, 12); 

Border titledBorder = new TitledBorder(lineBorder, "Hello", TitledBorder.LEFT, 
TitledBorder.BELOW_BOTTOM, font); 


public static TitledBorder createTitledBorder(Border border, String title, 
int justification, int position, Font font) 

Font font = new Font("Serif", Font.ITALIC, 12); 

Border titledBorder = BorderFactory.createTitledBorder(lineBorder, "Hello", 
TitledBorder.LEFT, TitledBorder.BELOW_ BOTTOM, font); 


public TitledBorder(Border border, String title, int justification, int position, 
Font font, Color color) 

Font font = new Font("Serif", Font.ITALIC, 12); 

Border titledBorder = new TitledBorder(lineBorder, "Hello", TitledBorder.LEFT, 
TitledBorder.BELOW_BOTTOM, font, Color.RED); 


public static TitledBorder createTitledBorder(Border border, String title, 
int justification, int position, Font font, Color color) 

Font font = new Font("Serif", Font.ITALIC, 12); 

Border titledBorder = BorderFactory.createTitledBorder(lineBorder, "Hello", 
TitledBorder.LEFT, TitledBorder.BELOW BOTTOM, font, Color.RED); 


Configuring Properties 


Unlike all the other predefined bordexs, titled borders have six setter methods to modify their 
attributes after border creation. As shown in Table 7-3, you can modify a titled border's under- 
lying border, title, drawing color, font, text justification, and text position. 


Table 7-3. TitledBorder Properties 


Property Name Data Type Access 

border Border Read-write 
borderO0paque boolean Read-only 
title String Read-write 
titleColor Color Read-write 
titleFont Font Read-write 
titleJustification int Read-write 


titlePosition int Read-write 
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Tip To reduce screen redrawing, it's better to modify the properties of a titled border prior to placing the 
border around a component. 


Text justification of the title string within a TitledBorder is specified by one of four class 
constants: 


+ CENTER: Place the title in the center. 


+ DEFAULT_JUSTIFICATION: Use the default setting to position the text. The value is equivalent 
to LEFT. 


+ LEFT: Place the title on the left edge. 
+ RIGHT: Place the title on the right edge. 


Figure 7-13 shows the same TitledBorder with three different justifications. 


¿ Justified Titled Borders 10 /xÍ 
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Figure 7-13. Title justifications 


You can position title strings in any one of six different locations, as specified by one of 
seven class constants: 


+ ABOVE_BOTTOM: Place the title above the bottom line. 

+ ABOVE_TOP: Place the title above the top line. 

+ BELOW_BOTTOM: Place the title below the bottom line. 

+ BELOW_TOP: Place the title below the top line. 

+ BOTTOM: Place the title on the bottom line. 

+ DEFAULT_POSITION: Use the default setting to place the text. This value is equivalent to TOP. 
+ TOP: Place the title on the top line. 


Figure 7-14 shows the six different positions available for the title on a TitledBorder. 
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Figure 7-14. Title positioning 


Because a TitledBorder contains another Border, you can combine more than one border 
to place multiple titles along a single border. For example, Figure 7-15 shows a title along the 
top and bottom of the border. 
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Figure 7-15. Showing multiple titles on a TitledBorder 
The program used to generate Figure 7-15 is shown in Listing 7-2. 


Listing 7-2. Multiple Titles on a TitledBorder 


import javax.swing.*; 
import javax.swing.border.*; 
import java.awt.*; 


public class DoubleTitle ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() £ 
public void run() £ 

JFrame frame = new JFrame("Double Title"); 

frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 

TitledBorder topBorder = BorderFactory.createTitledBorder("Top"); 

topBorder.setTitlePosition(TitledBorder.TOP); 

TitledBorder doubleBorder = new TitledBorder(topBorder, "Bottom", 
TitledBorder.RIGHT, TitledBorder.BOTTOM); 

JButton doubleButton = new JButton(); 

doubleButton.setBorder(doubleBorder); 

frame.add(doubleButton, BorderLayout.CENTER); 
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frame.setSize(300, 100); 
frame.setVisible(true); 
4 
5 
EventQueue.invokeLater(runner); 
J 
y 


Customizing TitledBorder Look and Feel 


The available set ofUTResource-related properties for a TitledBorder is shown in Table 7-4. 
It has three different properties. 


Table 7-4. TitledBorder UlResource Elements 


Property String Object Type 
TitledBorder. font Font 
TitledBorder.titleColor Color 
TitledBorder.border Border 


Creating Your Own Borders 


When you want to create your own distinctive border, you can either create a new class that 
implements the Border interface directly or you can extend the AbstractBorder class. As previ- 
ously mentioned, extendingthe AbstractBorder class is the better way to go, because optimizations 
are built in to certain Swing classes to take advantage of some of the AbstractBorder-specific 
methods. For instance, if a borderis an AbstractBorder, JComponent will reuse an Insets object 
when gettingthe Insets ofa border. Thus, one fewer object will need to be created and destroyed 
each time the insets are fetched. 

In addition to thinking about subclassing AbstractBorder versus implementing the Border 
interface yourself, you need to consider whether or not you want a static border. If you attach 
a border to a button, you want that button to be able to signal selection. You must examine the 
component passed into the paintBorder() method and react accordingly. In addition, you 
should also draw a disabled border to indicate when the component isn't selectable. Although 
setEnabled(false) disables the selection of the component, if the component has a border 
associated with it, the border still must be drawn, even when disabled. Figure 7-16 shows one 
border in action that looks at all these options for the component passed into the border's 
paintBorder() method. 


-lalxi 
| Hello | 
Brave New 
| World | 


Figure 7-16. Active custom border examples 
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The source for the custom border and the sample program is shown in Listing 7-3. 


Listing 7-3. Custom Colorized Border 


import javax.swing.*; 
import javax.swing.border.*; 
import java.awt.*; 


public class RedGreenBorder extends AbstractBorder ( 
public boolean isBorder0paque() ( 
return true; 
J 
public Insets getBorderInsets(Component c) ( 
return new Insets(3, 3, 3, 3); 
y 
public void paintBorder(Component c, Graphics g, int x, int y, int width, 
int height) ( 
Insets insets = getBorderInsets(c); 
Color horizontalColor; 
Color verticalColor; 
if (c.isEnabled()) £ 
boolean pressed = false; 
if (c instanceof AbstractButton) f 
ButtonModel model = ((AbstractButton)c).getModel (); 
pressed = model.isPressed(); 
J 
if (pressed) ( 
horizontalColor = Color.RED; 
verticalColor = Color.GREEN; 
) else £ 
horizontalColor = Color.GREEN; 
verticalColor = Color.RED; 
J 
j else [ 
horizontalColor = Color.LIGHT_GRAY; 
verticalColor = Color.LIGHT_GRAY; 
y 


g.setColor(horizontalColor); 


g.translate(x, y); 


// Top 
g-FillRect(0, O, width, insets.top); 
// Bottom 
g-FillRect(0, height-insets.bottom, width, insets.bottom); 
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g.setColor(verticalColor); 
// Left 
g-fillRect(0, insets.top, insets.left, height-insets.top-insets.bottom); 


/1R 


ight 


g-fillRect(width-insets.right, insets.top, insets.right, 
height-insets.top-insets.bottom); 
g-translate(-x, -y); 


J 


public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() £ 


h 


b 
b 


JFrame frame = 


elloButton.set 


new JFrame("My Border"); 


frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
Border border = new RedGreenBorder(); 
JButton helloButton = new JButton("Hello"); 


Border(border); 


Button braveButton = new JButton("Brave New"); 


raveButton.set 
raveButton.set 


worldButton.set 


+ 
E 
f 
+ 
+ 
) 
$; 


rame.add(hello 
rame.add(brave 
rame.add(world 


Border(border); 
Enabled(false); 


JButton worldButton = new JButton("Worl1d"); 


Border(border); 

Button, BorderLayout.NORTH) ; 
Button, BorderLayout.CENTER); 
Button, BorderLayout. SOUTH) ; 


rame.setSize(300, 100); 


rame.setVisibl 


e(true); 


EventQueue.invokeLater(runner); 


J 
J 


Note Another interesting custom border is one that displays an active component instead of a text title in 
a TitledBorder. Imagine a border that has a JCheckBox or JRadioButton instead of a text string for the 
title. You can also use a JLabel and pass in HTML for the text. 


Summary 


In this chapter, you learned about the use of the Border interface and its many predefined 
implementations. You also learned how to create predefined borders using the Factory design 
pattern provided by the BorderFactory class. Lastly, you saw how to define your own borders 
and why subclassing AbstractBorder is beneficial. 

In Chapter 8, you'Il move beyond low-level components and examine the window-like 
container objects available in Swing. 


CHAPTER 8 


Root Pane Containers 


l. Chapter 7, you looked at working with borders around Swing components. In this chapter, 
you'll explore the high-level Swing containers and discover how they differ from their AWT 
counterparts. 

Working with top-level containers in Swing is a bit different from working with top-level 
AWT containers. With the AWT containers of Frame, Window, Dialog, and Applet, you added 
components directly to the container, and there was only one place you could add them. In 
the Swing world, the top-level containers of JFrame, JWindow, JDialog, and JApplet, plus the 
JInternalFrame container, rely on something called a JRootPane. Instead of adding components 
directly to the container, you add them to a part of the root pane. The root pane then manages 
them all internally. 

Why was this indirect layer added? Believe itor not, itwas done to simplify things. The root 
pane manages its components in layers so that elements such as tooltip text will always appear 
above components, and you don't need to worry about dragging some components around 
behind others. 

The one container without an AWT counterpart, JInternalFrame, also provides some addi- 
tional capabilities when placed within a desktop (within a JDesktopPane to be specific). The 
JInternalFrame class can be used as the basis for creating a Multiple Document Interface (MDD 
application architecture within a Swing program. You can manage a series of internal frames 
within your program, and they”1l never go beyond the bounds of your main program window. 

Let's begin by exploring the new JRootPane class, which manages the internals of all the 
top-level containers. 


JRootPane Class 


The JRootPane class acts as a container delegate for the top-level Swing containers. Because 
the container holds only a JRootPane when you add or remove components from a top-level 
container, instead of directly altering the components in the container, you indirectly add or 
remove components from its JRootPane instance. In effect, the top-level containers are acting 
as proxies, with the JRootPane doing all the work. 

The JRootPane container relies on its inner class RootLayout for layout management and 
takes up all the space of the top-level container that holds it. There are only two components 
within a JRootPane: a JLayeredPane and a glass pane (Component). The glass pane is in front, can 
be any component, and tends to be invisible. The glass pane ensures that elements such as 
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tooltip text appear in front of any other Swing components. In the back is the JLayeredPane, 
which contains an optional JMenuBar on top and a content pane (Container) belowitin another 
layer. It is within the content pane that you would normally place components in the 
JRootPane. Figure 8-1 should help you visualize how the RootLayout lays out the components. 


JMenuBar 


Content Pane (Container) 


Glass Pane (Component) 


JLayeredPane 


Figure 8-1. JRootPane containment diagram 


Note A) LayeredPane is just another Swing container (it's described later in this chapter). lt can contain 
any components and has a special layering characteristic. The default JLayeredPane used within the 
JRootPane pane contains only a JMenuBar and a Container as its content pane. The content pane has 
its own layout manager, which is BorderLayout by default. 


Creating a JRootPane 


Although the JRootPane has a public no-argument constructor, a JRootPane isn't something 
you would normally create yourself. Instead, a class that implements the RootPaneContainer 
interface creates the JRootPane. Then, you can get the root pane from that component, through 
the RootPaneContainer interface, described shortly. 


JRootPane Properties 


As Table 8-1 shows, there are 11 properties of JRootPane. In most cases, when you get or set one 
ofthese properties for a top-level container, like JFrame, the container simply passes along the 
request to its JRootPane. 

The glass pane for a JRootPane must not be opaque. Because the glass pane takes up the 
entire area in front of the JLayeredPane, an opaque glass pane would render the menu bar and 
content pane invisible. And, because the glass pane and content pane share the same bounds, 
the optimizedDrawingEnabled property returns the visibility of the glass pane as its setting. 


Table 8-1. JRootPane Properties 
Property Name 
accessibleContext 
contentPane 
defaultButton 

glassPane 

jMenuBar 

layeredPane 
optimizedDrawingEnabled 
UI 

UlClassID 

validateRoot 


windowDecorationStyle 


Data Type 


AccessibleContext 
Container 

JButton 

Component 
JMenuBar 
JLayeredPane 
boolean 
RootPaneUl 

String 

boolean 


int 
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Access 
Read-only 


Read-write 
Read-write bound 
Read-write 
Read-write 
Read-write 
Read-only 
Read-write 
Read-only 
Read-only 


Read-write bound 


The windowDecorationStyle property is meant to describe the window adornments 
(border, title, buttons for closing window) for the window containing the JRootPane. It can 


be set to one of the following JRootPane class constants: 


+ COLOR CHOOSER DIALOG 
+ ERROR_DIALOG 

+ FILE CHOOSER DIALOG 
+ FRAME 

+ INFORMATION DIALOG 

+ NONE 

+ PLAIN DIALOG 

+ QUESTION DIALOG 


e WARNING _DIALOG 


What exactly happens with the windonDecorationStyle setting depends on the current 
look and feel. It is just a hint. By default, this setting is NONE. If this setting is not NONE, the 
setUndecorated() method of JDialog or JFrame has been called with a value of true, and the 
getSupportsWindonDecorations() method of the current look and feel reports true, then the 
look and feel, rather than the window manager, will provide the window adornments. This 
allows you to have programs with top-level windows that look like they do not come from the 
platform the user is working on but from your own environment, though still providing iconify, 
maximize, minimize, and close buttons. 
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For the Metal look and feel (and Ocean theme), getSupportsWindowDecorations() reports 
true. The other system-provided look and feel types report false. Figure 8-2 demonstrates 
what a frame looks like with the window adornments provided by the Metal look and feel. 


(5 Adornment Example 


Figure 8-2. Metal window adornments for a JFrame 
The source to produce Figure 8-2 is shown in Listing 8-1. 


Listing 8-1. Setting the Window Decoration Style 


import java.awt.*; 
import javax.swing.*; 


public class AdornSample ( 


public static void main(final String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("Adornment Example"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
frame.setUndecorated(true); 
frame.getRootPane().setWindowDecorationStyle(JRootPane. FRAME); 
frame.setSize(300, 100); 
frame.setVisible(true); 
y 
5 
EventQueue.invokeLater(runner); 
J 
) 


Customizing a JRootPane Look and Feel 


Table 8-2 shows the 12 UTResource-related properties for a JRootPane. Most of these settings have 
to do with the default border to use when configuring the window decoration style. 


Table 8-2. JRootPane UlResource Elements 


Property String Object Type 
RootPane.actionMap ActionMap 
RootPane.ancestorInputMap InputMap 


RootPane.colorChooserDialogBorder Border 
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Table 8-2. JRootPane UlResource Elements (Continued) 


Property String Object Type 
RootPane.defaultButtonWindowKeyBindings Object[ ] 
RootPane.errorDialogBorder Border 
RootPane.fileChooserDialogBorder Border 
RootPane.frameBorder Border 
RootPane.informationDialogBorder Border 
RootPane.plainDialogBorder Border 
RootPane.questionDialogBorder Border 
RootPane.warningDialogBorder Border 
RootPaneUI String 


RootPaneContainer Interface 


The RootPaneContainer interface defines the setter/getter methods for accessing the different 
panes within the JRootPane, as well as accessing the JRootPane itself. 


public interface RootPaneContainer ( 
// Properties 
public Container getContentPane(); 
public void setContentPane(Container contentPane); 
public Component getGlassPane(); 
public void setGlassPane(Component glassPane); 
public JLayeredPane getLayeredPane(); 
public void setLayeredPane(JLayeredPane layeredPane); 
public JRootPane getRootPane(); 


Among the predefined Swing components, the JFrame, Juindow, JDialog, JApplet, and 
JInternalFrame classes implement the RootPaneContainer interface. For the most part, these 
implementations simply pass along the request to a JRootPane implementation for the high- 
level container. The following source code is one such implementation for the glass pane ofa 
RootPaneContainer implementer: 


public Component getGlassPane() ( 
return getRootPane().getGlassPane(); 


J 


public void setGlassPane(Component glassPane) ( 
getRootPane().setGlassPane(glassPane); 


J 
JLayeredPane Class 


The JLayeredPane serves as the main component container of a JRootPane. The JLayeredPane 
manages the z-order, or layering, of components within itself. This ensures that the correct 
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component is drawn on top of other components for tasks such as creating tooltip text, pop-up 
menus, and dragging for drag-and-drop. You can use the system-defined layers, or you can 
create your own layers. 

Although initially a JLayeredPane container has no layout manager, there's nothing to stop 
you from setting the layout property of the container, defeating the layering aspect of the 
container. 


Creating a JLayeredPane 


As with the JRootPane, you'll almost never create an instance ofthe JLayeredPane class yourself. 
When the default JRootPane is created for one of the predefined classes that implement 
RootPaneContainer, the JRootPane creates a JLayeredPane for its main component area, adding 
an initial content pane. 


Adding Components in Layers 


A layer setting for each added component manages the z-order of components within a 
JLayeredPane. The higher the layer setting, the closer to the top the component will be drawn. 
You can set the layer with the layout manager constraints when you add a component to a 
JLayeredPane: 


Integer layer = new Integer(20); 
alayeredPane.add(aComponent, layer); 


You can also call the public void setLayer(Component comp, int layer) or public void 
setLayer(Component comp, int layer, int position) method before adding the component 
to the JLayeredPane. 


alayeredPane.setLayer(aComponent, 10); 
alayeredPane.add(aComponent); 


The JLayeredPane class predefines six constants for special values. In addition, you can 
find out the topmost current layer with public int c and the bottom layer with public int 
lowestLayer(). Table 8-3 lists the six predefined layer constants. 


Table 8-3. JLayeredPane Layer Constants 


Constant Description 

FRAME_CONTENT_LAYER Level -30,000 for holding the menu bar and content pane; 
not normally used by developers 

DEFAULT_LAYER Level 0 for the normal component level 

PALETTE_LAYER Level 100 for holding floating toolbars and the like 

MODAL_LAYER Level 200 for holding pop-up dialog boxes that appear on top 


of components on the default layer, on top of palettes, and 
below pop-ups 


POPUP_LAYER Level 300 for holding pop-up menus and tooltips 
DRAG_LAYER Level 400 for ensuring that dragged objects remain on top 
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Although you can use your own constants for layers, use them with care—because the 
system will use the predefined constants for ¿fs needs. If your constants don't fit in properly, 
the components may not work as you intended. 

To visualize how the different layers fit in, see Figure 8-3. 


FRAME_CONTENT_LAYER/-30000 


DEFAULT_LAYER/O 


PALETTE_LAYER/100 


MODAL_LAYER/200 


POPUP_LAYER/300 


DRAG_LAYER/400 


Figure 8-3. JLayeredPane layers 


Working with Component Layers and Positions 


Components in a JLayeredPane have both a layer and a position. When a single component is 
on a layer, it's at position 0. When multiple components are on the same layer, components 
added later have higher position numbers. The lower the position setting, the closer to the top 
the component will appear. (This is the reverse ofthe layering behavior.) Figure 8-4 shows the 
positions for four components on the same layer. 

To rearrange components on a single layer, you can use either the public void 
moveToBack(Component component) or public void moveToFront(Component component) 
method. When you move a component to the front, it goes to position O for the layer. When 
you move a component to the back, it goes to the highest position number for the layer. You 
can also manually set the position with public void setPosition(Component component, int 
position). A position of —1 is automatically the bottom layer with the highest position (see 
Figure 8-4). 


241 


242 


CHAPTER 8 ROOT PANE CONTAINERS 


POSITION=3 (OR-1) 


POSITION=2 


POSITION=1 


POSITION=0 


Figure 8-4. JLayeredPane positions 


JLayeredPane Properties 


Table 8-4 shows the two properties of JLayeredPane. The optimizedDrawingEnabled property 
determines whether components within the JLayeredPane can overlap. By default, this setting 
is true because in the standard usage with JRootPane the JMenuBar and content pane can't 
overlap. However, the JLayeredPane automatically validates the property setting to reflect the 
current state of the contents of the pane. 


Table 8-4. JLayeredPane Properties 


Property Name Data Type Access 
accessibleContext AccessibleContext Read-only 
optimizedDrawingEnabled boolean Read-only 


JFrame Class 


The JFrame class is the Swing high-level container that uses a JRootPane and implements the 
RootPaneContainer interface. In addition, ituses the WindonConstants interface to help manage 
closing operations. 


CHAPTER 8 ROOT PANE CONTAINERS 


Creating a JFrame 


The JFrame class provides two primary constructors: one for creating a frame without a title 
and one for creating a frame with a title. There are two additional constructors for creating 
frames with a specialized GraphicsConfiguration. 


public JFrame() 
JFrame frame = new JFrame(); 


public JFrame(String title) 
JFrame frame = new JFrame("Title Bar"); 


public JFrame(GraphicsConfiguration config) 

GraphicsEnvironment ge = GraphicsEnvironment.getlLocalGraphicsEnvironment(); 
GraphicsDevice gsd[] = ge.getScreenDevices(); 

GraphicsConfiguration gc[] = gsd[0].getConfigurations(); 

JFrame frame = new JFrame(gc[0]); 


public JFrame(String title, GraphicsConfiguration config) 


GraphicsConfiguration gc = ...; 
JFrame frame = new JFrame("Title Bar", gc); 


JFrame Properties 


Table 8-5 shows the nine properties of the JFrame. 


Table 8-5. JFrame Properties 


Property Name Data Type Access 

accessibleContext AccessibleContext Read-only 
contentPane Container Read-write 
defaultClose0peration int Read-write 
glassPane Component Read-write 
iconImage Image Write-only 
jMenuBar JMenuBar Read-write 
layeredPane JLayeredPane Read-write 
layout LayoutManager Write-only 


rootPane JRootPane Read-only 
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Although most properties are the result ofimplementing the RootPaneContainer interface, 
two properties are special: defaultCloseOperation and layout. (You first looked at the 
defaultClose0peration property in Chapter 2.) By default, a JFrame hides itself when the user 
closes the window. To change the setting, you can use one of the constants listed in Table 8-6 
as arguments when setting the default close operation. The first comes from JFrame directly; 
the others are part of the WindowConstants interface. 


aFrame.setDefaultCloseOperation(JFrame.DISPOSE ON CLOSE); 


Table 8-6. Close Operation Constants 


Constant Description 

EXIT_ON_CLOSE Call System.exit(0). 

DISPOSE_ON_CLOSE Call dispose() on the frame. 

DO_NOTHING_ON_CLOSE Ignore the request. 

HIDE_ON_CLOSE Call setVisible(false) on the frame; this is the default. 


The layout property is odd. By default, settingthe layout manager ofthe JFrame passes the 
call along to the content pane. You can't change the default layout manager of the JFrame. 


Tip You can use the state property (inherited from Frame) to say whether the JFrame is currently icon- 
ified. When using the property, be sure to use one of the additional Frame constants of NORMAL or ICONIFTED to 
set its state. 


There is an additional static property of JFrame: defaultLookAndFeelDecorated. This works 
with the windonDecorationStyle property of JRootPane. When setto true, newly created frames 
will be adorned with decorations from the look and feel instead ofthe window manager. Of 
course, this happens only if the current look and feel supports window decorations. Listing 8-2 
shows an alternate way to generate the same screen (with the window adornments provided by 
the Metal look and feel) as the one shown earlier in Figure 8-2. 


Listing 8-2. Alternative Way of Setting the Window Decoration Style 


import java.awt.*; 
import javax.swing.*; 


public class AdornSample2 ( 
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public static void main(final String args[]) ( 
Runnable runner = new Runnable() 4 
public void run() £ 
JFrame.setDefaultLookAndFeelDecorated(true); 
JFrame frame = new JFrame("Adornment Example"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
frame.setSize(300, 100); 
frame.setVisible(true); 
) 
5 
EventQueue.invokelLater(runner); 
) 
J 


Adding Components to a JFrame 


Because JFrame implements the RootPaneContainer interface and uses a JRootPane, you don't 
add components directly to the JFrame. Instead, you add them to the JRootPane contained 
within the JFrame. Prior to J2SE 5.0, you needed to add components like this: 


JRootPane rootPane = aJFrame.getRootPane(); 
Container contentPane = rootPane.getContentPane(); 
contentPane.add(...); 


This can be shortened to the following form: 
aJFrame.getContentPane().add(...); 


If you tried to add components directly to the JFrame, it resulted in a runtime error being 
thrown. 

Due to many suggestions (complaints?), Sun finally decided to change the add() method 
into a proxy: 


// 32SE 5.0 
aJFrame.add(...); 


With J2SE 5.0, when you add components to the JFrame, they actually are added to the 
content pane of the RootPaneContainer. 


Handling JFrame Events 


The JFrame class supports the registration of eleven different listeners: 
+ ComponentListener: To find out when the frame moves or is resized. 


+ ContainerListener: Normally not added to a JFrame because you add components to the 
content pane ofits JRootPane. 


e FocusListener: To find out when the frame gets or loses input focus. 
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HierarchyBoundsListener: To find out when the frame moves or is resized. This works 
similarly to ComponentListener, since the frame is the top-level container of component. 


HierarchyListener: To find out when the frame is shown or hidden. 
InputMethodListener: To work with input methods for internationalization. 


KeyListener: Normally not added to a JFrame. Instead, you register a keyboard action for 
its content pane, like this: 


JPanel content = (JPanel)frame.getContentPane(); 

KeyStroke stroke = KeyStroke.getKeyStroke(KeyEvent.VK_ESCAPE, 0); 

content .registerKeyboardAction(actionListener, stroke, 
JComponent .WHEN_IN_FOCUSED WINDOW); 


MouseListener and MouseMotionListener: To listen for mouse and mouse motion events. 
PropertyChangeListener: To listen for changes to bound properties. 


WindowListener: To find out when a windowis iconified or deiconified or a user is trying 
to open or close the window. 


With the help of the defaultClose0peration property, you typically don't need to add a 


WindowListener to help with closing the frame or stopping the application. 


Extending JFrame 


If you need to extend JFrame, this class has two important protected methods: 


protected void frameInit() 
protected JRootPane createRootPane() 


By overriding either of these methods in a subclass, you can customize the initial appear- 


ance and behavior of the frame or that ofits JRootPane. For example, in the ExitableJFrame 
class shown in Listing 8-3, the default close operation is initialized to the EXIT_ON_CLOSE state. 
Instead of calling setDefaultClose0peration() for every frame created, you can use this class 
instead. Because JFrame was subclassed, you don't need to add a call to the frameInit() 
method in either of the constructors. The parent class automatically calls the method. 


Listing 8-3. Closing Frames by Default 


import javax.swing.JFrame; 
public class ExitableJFrame extends JFrame ( 
public ExitableJFrame () £ 


J 


public ExitableJFrame (String title) ( 


y 


super (title); 
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protected void frameInit() ( 
super. frameInit(); 
setDefaultCloseOperation(EXIT_ON CLOSE); 
) 
J 


Caution If you do override the frameInit () method of JFrame, remember to call super. frameInit() 
first, to initialize the default behaviors. If you forget and don't reimplement all the default behaviors yourself, 
your new frame will look and act differently. 


JWindow Class 


The JWindow class is similar to the JFrame class. Ituses a JRootPane for component management 
and implements the RootPaneContainer interface. Basically, it is a top-level window with no 
adornments. 


Creating a Window 


The JWindow class has five constructors: 


public JWindow() 
JWindow window = new JWindow(); 


public JWindow(Frame owner) 
JWindow window = new JWindow(aFrame); 


public JWindow(GraphicsConfiguration config) 
GraphicsConfiguration gc = ...; 
JWindow window = new JWindow(gc); 


public JWindow(Window owner) 
JWindow window = new JWindow(anotherWindow) ; 


public JWindow(Window owner, GraphicsConfiguration config) 
GraphicsConfiguration gc = ...; 
JWindow window = new JWindow(anotherWindow, gc); 


You can create a window without specifying a parent or by specifying the parent as a Frame 
or Window. If no parent is specified, an invisible one is used. 
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JWindow Properties 


Table 8-7 lists the six properties of Juindow. These are similarin nature to the JFrame properties, 
except that JWindow has no property for a default close operation or a menu bar. 


Table 8-7. Window Properties 


Property Name Data Type Access 

accessibleContext AccessibleContext Read-only 
contentPane Container Read-write 
glassPane Component Read-write 
layeredPane JLayeredPane Read-write 
layout LayoutManager Write-only 
rootPane JRootPane Read-only 


Handling JWindow Events 


The JWindow class adds no additional event-handling capabilities beyond those of the JFrame 
and Window classes. See the “Handling JFrame Events” section earlier in this chapter for a list of 
listeners you can attach to a JWindow. 


Extending JWindow 


If you need to extend JWindow, the class has two protected methods ofimportance: 


protected void windowInit() 
protected JRootPane createRootPane() 


JDialog Class 


The JDialog class represents the standard pop-up window for displaying information related 
to a Frame. It acts like a JFrame, whereby its JRootPane contains a content pane and an optional 
JMenuBar, and itimplements the RootPaneContainer and WindowConstants interfaces. 


Creating a JDialog 

There are 11 constructors for creating JDialog windows: 
public JDialog() 

JDialog dialog = new JDialog(); 


public JDialog(Dialog owner) 
JDialog dialog = new JDialog(anotherDialog); 
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public JDialog(Dialog owner, boolean modal) 
Dialog(anotherDialog, true); 


JDialog dialog = new 


JDialog dialog = new 


JDialog dialog = new 


public JDialog(Dialog 


public JDialog(Dialog 


owner, String title) 
Dialog(anotherDialog, "Hello"); 


owner, String title, boolean modal) 
Dialog(anotherDialog, "Hello", true); 
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public JDialog(Dialog owner, String title, boolean modal, GraphicsConfiguration gc) 
GraphicsConfiguration gc = ...; 


JDialog dialog = new 


public JDialog(Frame 
JDialog dialog = new 


public JDialog(Frame 
JDialog dialog = new 


public JDialog(Frame 
JDialog dialog = new 


public JDialog(Frame 
JDialog dialog = new 


owner) 
JDialog(aFrame); 


JDialog(anotherDialog, "Hello", true, gc); 


owner, String windowTitle) 
JDialog(aFra 


e, "Hello"); 


owner, boolean modal) 
JDialog(aFra 


e, false); 


owner, String title, boolean modal) 
JDialog(aFra 


e, "Hello", true); 


public JDialog(Frame owner, String title, boolean modal, GraphicsConfiguration gc) 
GraphicsConfiguration gc = ...; 
JDialog dialog = new JDialog(aFrame, "Hello", true, gc); 


Note Instead of manually creating a JDialog and populating it, you may find yourself having JOptionPane 
automatically create and fill the JDialog for you. You'll explore the JOptionPane component in Chapter 9. 


Each constructor allows you to customize the dialog owner, the window title, and the 
modality of the pop-up. When a JDialog is modal, it blocks input to the owner and the rest of 
the application. When a JDialog is nonmodal, it allows a user to interact with the JDialog as 
well as the rest of your application. 


Caution For modality to work properly among the different Java versions, avoid mixing heavyweight AWT 
components with lightweight Swing components in a JDialog. 
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JDialog Properties 


Other than the settable icon image, the JDialog class has the same properties as JFrame. These 
eight properties are listed in Table 8-8. 


Table 8-8. JDialog Properties 


Property Name Data Type Access 

accessibleContext AccessibleContext Read-only 
contentPane Container Read-write 
defaultClose0peration int Read-write 
glassPane Component Read-write 
jMenuBar JMenuBar Read-write 
layeredPane JLayeredPane Read-write 
layout LayoutManager Write-only 
rootPane JRootPane Read-only 


The constants to use for specifying the default close operation are the WindowConstants shown 
earlier in Table 8-6 (basically all but EXIT_ON_CLOSE). By default, the defaultClose0peration 
property is set to HIDE_ON_CLOSE, which is the desirable default behavior for a dialog pop-up. 

Like JFrame, JDialog also has a static defaultLookAndFeelDecorated property. This controls 
whether or not dialogs are decorated by the look and feel, by default. 


Handling JDialog Events 


There are no special JDialog events for you to deal with; it has the same events as those for the 
JFrame class. 

One thing that you may want to do with a JDialog is specify that pressing the Escape key 
cancels the dialog. The easiest way to do this is to register an Escape keystroke to a keyboard 
action within the JRootPane of the dialog, causing the JDialog to become hidden when Escape 
is pressed. Listing 8-4 demonstrates this behavior. Most ofthe source duplicates the constructors 
of JDialog. The createRootPane() method maps the Escape key to the custom Action. 


Listing 8-4. A JDialog That Closes When Escape Is Pressed 


import javax.swing.*; 
import java.awt.*; 
import java.awt.event.*; 


public class EscapeDialog extends JDialog f 
public EscapeDialog() ( 
this((Frame)null, false); 
J 
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public EscapeDialog(Frame owner) ( 
this(owner, false); 
) 
public EscapeDialog(Frame owner, boolean modal) ( 
this(owner, null, modal); 


public EscapeDialog(Frame owner, String title) ( 
this(owner, title, false); 


public EscapeDialog(Frame owner, String title, boolean modal) ( 
super(owner, title, modal); 


public EscapeDialog(Frame owner, String title, boolean modal, 
GraphicsConfiguration gc) £ 
super(owner, title, modal, gc); 


public EscapeDialog(Dialog owner) ( 
this(owner, false); 
y 
public EscapeDialog(Dialog owner, boolean modal) ( 
this(owner, null, modal); 
J 
public EscapeDialog(Dialog owner, String title) ( 
this(owner, title, false); 
J 
public EscapeDialog(Dialog owner, String title, boolean modal) ( 
super(owner, title, modal); 
y 
public EscapeDialog(Dialog owner, String title, boolean modal, 
GraphicsConfiguration gc) £ 
super(owner, title, modal, gc); 
y 
protected JRootPane createRootPane() f 
JRootPane rootPane = new JRootPane(); 
KeyStroke stroke = KeyStroke.getKeyStroke("ESCAPE"); 
Action actionListener = new AbstractAction() f 
public void actionPerformed(ActionEvent actionEvent) ( 
setVisible(false); 
J 
8 
InputMap inputMap = rootPane.getInputMap(JComponent.WHEN_IN_FOCUSED WINDOW) ; 
inputMap.put(stroke, "ESCAPE"); 
rootPane.getActionMap().put("ESCAPE", actionListener); 


return rootPane; 
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Note !f you use the static creation methods of JOptionPane, the JDialog windows it creates automat- 
ically have the Escape key registered to close the dialog. 


Extending JDialog 


If you need to extend JDialog, the class has two protected methods ofimportance: 


protected void dialogInit() 
protected JRootPane createRootPane() 


The latter method is demonstrated in the previous example in Listing 8-4. 


JApplet Class 


The JApplet class is an extension to the AWT Applet class. For event handling to work properly 
within applets that use Swing components, your applets must subclass JApplet instead of 
Applet. 

The JApplet works the same as the other high-level containers by implementing the 
RootPaneContainer interface. One important difference between JApplet and Applet is the default 
layout manager. Because you add components to the content pane of a JApplet, its default 
layout manager is BorderLayout. This is unlike the default layout manager of Applet, which is 
FlowLayout. In addition, Swing applets can also have a menu bar, or more specifically a JMenuBar, 
which is just another attribute of the JRootPane of the applet. 

If you plan to deploy an applet that uses the Swing components, itis best to use the Java 
Plug-in from Sun Microsystems, because that will install the Swing libraries with the runtime. 


Tip To make sure you are running the Java Plug-in under Internet Explorer, select Internet Options from 
the Tools menu, and then choose the Advanced tab. Scroll down to the Java section immediately above 
Microsoft VM and make sure Use JRE [VERSION] for <applet> (requires restart) is selected. If [VERSION] isn't 
recent enough, you?I! need to get a newer version from Sun at http://www. java.com. 


If you need to extend the JApplet class, it has only one protected method ofimportance: 


protected JRootPane createRootPane() 


Working with a Desktop 


Swing provides for the management of a set of frames within a common window or desktop. As 
discussed in Chapter 1, this management is commonly called MDI. The frames can be layered 
on top of one another or dragged around, and their appearance is specific to the current 
look and feel. The frames are instances of the JInternalFrame class, whereas the desktop is a 
specialized JLayeredPane called JDesktopPane. The management of the frames within a desktop 
is the responsibility of a DesktopManager, in which the default implementation that's provided 
is DefaultDesktopManager. The iconified form of a JInternalFrame on the desktop is represented 
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bythe JDesktopIcon inner class of JInternalFrame. There are also an InternalFrameListener, 
InternalFrameAdapter, and InternalFrameEvent for event handling. 

First, let's look at the parts that make up the desktop, and then you'll see a complete example 
that uses all the parts. 


Note The Swing libraries provide only those tools necessary to build an application using MDI. You use 
these tools in whatever manner you see fit. 


JInternalFrame Class 


The JInternalFrame class is similar to the JFrame class. It acts as a high-level container, using 
the RootPaneContainer interface, but itisn't a top-level window. You must place internal frames 
within another top-level window. When dragged around, internal frames stay within the bounds 
of their container, which is usually a JDesktopPane. In addition, internal frames are lightweight 
and therefore offer a Ul-delegate to make internal frames appear as the currently configured 
look and feel. 


Note As with the creation of a JFrame, the JInternalFrame is hidden when first created. 


Creating a JinternalFrame 


There are six constructors for JInternalFrame: 


public JInternalFrame() 


JInternalFrame frame = new JInternalFrame(); 


public JInternalFrame(String title) 
JInternalFrame frame = new JInternalFrame("The Title"); 


public JInternalFrame(String title, boolean resizable) 
JInternalFrame frame = new JInternalFrame("The Title", true); 


public JInternalFrame(String title, boolean resizable, boolean closable) 
JInternalFrame frame = new JInternalFrame("The Title", false, true); 


public JInternalFrame(String title, boolean resizable, boolean 
closable, boolean maximizable) 
JInternalFrame frame = new JInternalFrame("The Title", true, false, true); 


public JInternalFrame(String title, boolean resizable, boolean 
closable, boolean maximizable, boolean iconifiable) 
JInternalFrame frame = new JInternalFrame("The Title", false, true, false, true); 
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These constructors cascade in such a way that each adds a parameter to another constructor. 
With no arguments, the created JInternalFrame has no title and can't be resized, closed, 
maximized, or iconified. Internal frames can always be dragged, however. 


Note In addition to your creating a JInternalFrame directly, you can rely on the JOptionPane to 
create an internal frame for common pop-up dialog boxes hosted by a JInternalFrame instead of being 


hosted by the standard JDialog. 


JinternalFrame Properties 


The 30 different properties for the JInternalFrame class are listed in Table 8-9. The layer property 
is listed twice as it has two setter methods, one for an int and another for an Integer. 


Table 8-9. JInternalFrame Properties 


Property Name 


accessibleContext 
closable 

closed 

contentPane 
defaultClose0peration 
desktopIcon 
desktopPane 
focusCycleRoot 
focusCycleRootAncester 
focusOwner 

framelcon 

glassPane 

icon 

iconifiable 
internalFrameListeners 
jMenuBar 

layer 

layer 


layeredPane 


Data Type 


AccessibleContext 
boolean 

boolean 

Container 

int 
JInternalFrame.JDesktopIcon 
JDesktopPane 

boolean 

Container 

Component 

Icon 

Component 

boolean 

boolean 
InternalFrameListener[ ] 
JMenuBar 

int 

Integer 


JLayeredPane 


Access 
Read-only 


Read-write bound 
Read-write bound constrained 
Read-write bound 

Read-write 

Read-write bound 

Read-only 

Read-write 

Read-only 

Read-only 

Read-write bound 

Read-write bound 
Read-write bound constrained 
Read-write 

Read-only 

Read-write bound 

Read-write 

Write-only 


Read-write bound 
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Table 8-9. JInternalFrame Properties (Continued) 


Property Name Data Type Access 

layout LayoutManager Write-only 

maximizable boolean Read-write bound 

maximum boolean Read-write bound constrained 
mostRecentFocusOwner Component Read-only 

normalBounds Rectangle Read-write 

resizable boolean Read-write bound 

rootPane JRootPane Read-only bound 

selected boolean Read-write bound constrained 
title String Read-write bound 

UI InternalFrameUul Read-write 

UlClassID String Read-only 

warningString String Read-only 


The initial defaultClose0peration property setting for a JInternalFrame is DISPOSE_ON_CLOSE 
for Java 1.3 releases and later. Earlier releases had a default setting of HIDE_ON_CLOSE. You can 
set this property to any of the WindowConstants settings shown earlier in Table 8-6. 

The normalBounds property describes where an iconified internal frame would appear 
when deiconified. The focusOwner property provides the actual Component with the input focus 
when the specific JInternalFrame is active. 

The JInternalFrame contains the only four constrained properties within the Swing classes: 
closed, icon, maximum, and selected. They're directly related to the four boolean constructor 
parameters. Each allows you to check on the current state of the property as well as change its 
setting. However, because the properties are constrained, whenever you try to set one, the 
attempt must be in a try-catch block, catching PropertyVetoException: 


try ( 
// Try to iconify internal frame 
internalFrame.setIcon(false); 

) catch (PropertyVetoException propertyVetoException) ( 
System.out.println("Rejected"); 


J 


To help you work with some of the bound properties, the JInternalFrame class defines 
11 constants, as listed in Table 8-10. They represent the string that should be returned by 
getPropertyName() for a PropertyChangeEvent within a PropertyChangeListener. 
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Table 8-10. JInternalFrame Property Constants 


Property Name Constant Associated Property 
CONTENT_PANE_PROPERTY contentPane 
FRAME_ICON_ PROPERTY framelcon 
GLASS PANE PROPERTY glassPane 
IS CLOSED PROPERTY closed 
IS_ICON PROPERTY icon 

IS MAXIMUM PROPERTY maximum 

IS SELECTED PROPERTY selected 
LAYERED_PANE_PROPERTY layeredPane 
MENU_BAR_ PROPERTY jMenuBar 
ROOT_PANE_PROPERTY rootPane 
TITLE PROPERTY title 


The following class example demonstrates the use of the constants within a 
PropertyChangeListener. 


import java.beans.*; 
import javax.swing.*; 


public class InternalFramePropertyChangeHandler implements PropertyChangelistener ( 
public void propertyChange(PropertyChangeEvent propertyChangeEvent) ( 
String propertyName = propertyChangeEvent.getPropertyName(); 
if (propertyName.equals(JInternalFrame.IS ICON PROPERTY)) ( 
System.out.println("Icon property changed. React."); 
J 
J 
y 


Handling JinternalFrame Events 


To help you use a JInternalFrame as you would use a JFrame, there's an additional event listener 
for responding to internal frame opening- and closing-related events. The interface is 
called InternalFrameListener, and its definition follows. It works similarly to the AWT 
WindowListener interface, but with a JInternalFrame instead of an AWT Window class. 


public interface InternalFrameListener extends EventListener ( 

public void internalFrameActivated(InternalFrameEvent internalFrameEvent); 
public void internalFrameClosed(InternalFrameEvent internalFrameEvent); 
public void internalFrameClosing(InternalFrameEvent internalFrameEvent); 
public void internalFrameDeactivated(InternalFrameEvent internalFrameEvent); 
public void internalFrameDeiconified(InternalFrameEvent internalFrameEvent); 
public void internalFramelconified(InternalFrameEvent internalFrameEvent); 
public void internalFrameOpened(InternalFrameEvent internalFrameEvent); 


CHAPTER 8 ROOT PANE CONTAINERS 


In addition, like the WindowAdapter class that has all the WindowListener methods stubbed 
out, there is an InternalFrameAdapter class with all the InternalFrameListener methods stubbed 
out. If you're not interested in all the event happenings of a JInternalFrame, you can subclass 
InternalFrameAdapter and override only those methods you're interested in. For instance, the 
listener shown in Listing 8-5 is interested in only the iconification methods. Instead of providing 
stubs for the other five methods of InternalFrameListener, you would need to subclass only 
InternalFrameAdapter and override the two relevant methods. 


Listing 8-5. Custom InternalFrameListener 


import javax.swing.*; 
import javax.swing.event.*; 


public class InternalFramelconifyListener extends InternalFrameAdapter ( 
public void internalFramelconified(InternalFrameEvent internalFrameEvent) ( 
JInternalFrame source = (JInternalFrame)internalFrameEvent.getSource(); 
System.out.println ("Iconified: " + source.getTitle()); 
) 
public void internalFrameDeiconified(InternalFrameEvent internalFrameEvent) ( 
JInternalFrame source = (JInternalFrame)internalFrameEvent.getSource(); 
System.out.println ("Deiconified: " + source.getTitle()); 
) 
) 


The InternalFrameEvent class is a subclass of AWTEvent. To define the values returned by 
the public int getID() method of AWTEvent, the InternalFrameEvent class defines a constant 
for each of the specific event subtypes that can be used. In addition, two other constants desig- 
nate the range of valid values. Table 8-11 lists the nine constants. You can also get the actual 
JInternalFrame from the event with getInternalFrame(). 


Table 8-11. InternalFrameEvent Event Subtypes 


Event Subtype ID Associated Interface Method 
INTERNAL_FRAME_ACTIVATED internalFrameActivated 
INTERNAL_FRAME_ CLOSED internalFrameClosed 
INTERNAL_FRAME_CLOSING internalFrameClosing 
INTERNAL_FRAME_DEACTIVATED internalFrameDeactivated 
INTERNAL_FRAME _DEICONIFIED internalFrameDeiconified 
INTERNAL_FRAME_FIRST N/A 
INTERNAL_FRAME_ICONIFTED internalFramelconified 
INTERNAL_FRAME_LAST N/A 
INTERNAL_FRAME_OPENED internalFrameOpened 


Customizing a JinternalFrame Look and Feel 


Because the JInternalFrame is a lightweight component, it has an installable look and feel. 
Each installable Swing look and feel provides a different JInternalFrame appearance and set of 
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default UTResource values. Figure 8-5 shows the appearance of the JWindow container for the 
preinstalled set of look and feel types. 


£- Motif LnF 


Not Iconifiable 


Motif 


£ Windows LnF 


¿ Can Do All 


Can Do All 


Z Not Iconifiable 


Not Iconifiable 


Windows 


ECT as 


Not Iconifiable 


] 


[E] not Maximiza... TT [E not Resizable | 


Ocean 


Figure 8-5. JInternalFrame under different look and feel types 
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The available set of UIResource-related properties for a JInternalFrame is shown in 
Table 8-12. For the JInternalFrame component, there are 60 different properties, including 


those for the internal frame's title pane. 


Table 8-12. JInternalFrame UlResource Elements 


Property String 

InternalFrame.actionMap 
InternalFrame.activeBorderColor 
InternalFrame.activeTitleBackground 
InternalFrame.activeTitleForeground 
InternalFrame.activeTitleGradient 
InternalFrame.border 
InternalFrame.borderColor 
InternalFrame.borderDarkShadow 
InternalFrame.borderHighlight 
InternalFrame.borderLight 
InternalFrame.borderShadow 
InternalFrame.borderWidth 
InternalFrame.closeButtonToolTip 
InternalFrame.closelcon 
InternalFrame.closeSound 
InternalFrame.icon 
InternalFrame.iconButtonTool1Tip 
InternalFrame.iconifyIcon 
InternalFrame.inactiveBorderColor 
InternalFrame.inactiveTitleBackground 
InternalFrame.inactiveTitleForeground 
InternalFrame.inactiveTitleGradient 
InternalFrame.layoutTitlePaneAtOrigin 
InternalFrame.maxButtonTool1Tip 
InternalFrame.maximizelcon 
InternalFrame.maximizeSound 
InternalFrame.minimizelcon 


InternalFrame.minimizelconBackground 


InternalFrame.minimizeSound 


Object Type 
ActionMap 
Color 
Color 
Color 
List 
Border 
Color 
Color 
Color 
Color 
Color 
Integer 
String 
Icon 
String 
Icon 
String 
Icon 
Color 
Color 
Color 
List 
Boolean 
String 
Icon 
String 
Icon 
Color 


String 
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Table 8-12. JInternalFrame UlResource Elements (Continued) 


Property String Object Type 
InternalFrame.optionDialogBorder Border 
InternalFrame.paletteBorder Border 
InternalFrame.paletteCloselcon Icon 
InternalFrame.paletteTitleHeight Integer 
InternalFrame.resizelconHighlight Color 
InternalFrame.resizelconShadow Color 
InternalFrame.restoreButtonToolTip String 
InternalFrame.restoreDownSound String 
InternalFrame.restoreUpSound String 
InternalFrame.titleButtonHeight Integer 
InternalFrame.titleButtonWidth Integer 
InternalFrame.titleFont Font 
InternalFrame.titlePaneHeight Integer 
InternalFrame.useTaskBar Boolean 
InternalFrame.windonBindings Object[ ] 
InternalFrameTitlePane.closeButtonAccessibleName String 
InternalFrameTitlePane.closeButtonText String 
InternalFrameTitlePane.closelcon Icon 
InternalFrameTitlePane.iconifyButtonAccessibleName String 
InternalFrameTitlePane.iconifyIcon Icon 
InternalFrameTitlePane.maximizeButtonAccessibleName String 
InternalFrameTitlePane.maximizeButtonText String 
InternalFrameTitlePane.maximizelcon Icon 
InternalFrameTitlePane.minimizeButtonText String 
InternalFrameTitlePane.minimizelcon Icon 
InternalFrameTitlePane.moveButtonText String 
InternalFrameTitlePane.restoreButtonText String 
InternalFrameTitlePane.sizeButtonText String 
InternalFrameTitlePane.titlePaneLayout LayoutManager 
InternalFrameTitlePaneUI String 
InternalFrameUl String 
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In addition to the many configurable properties in Table 8-12, with the Metal look and 
feel, you can designate an internal frame to be a “palette” by using a special client property, 
JInternalFrame.isPalette. When set to Boolean. TRUE, this internal frame will have a slightly 
different appearance from the others and a shorter title bar, as shown in Figure 8-6. 


Not Closable 


| (O Not maximizable e | 
| E Not iconifiable 


Not Iconifiable 


Palette 


Figure 8-6. A JInternalFrame palette with other frames 


If you also add an internal frame to the PALETTE_LAYER of the desktop, the frame will always 
appear on top of all the other frames (as noted in Figure 8-6): 


JInternalFrame palette = new JInternalFrame("Palette", true, false, true, false); 
palette.setBounds(150, 0, 100, 100); 
palette.putClientProperty("JInternalFrame.isPalette", Boolean.TRUE); 
desktop.add(palette, JDesktopPane.PALETTE_LAYER); 


The complete source for creating the program in Figure 8-6 appears in Listing 8-6 later in 
this chapter. 


Note If the current look and feel is something other than Metal, the palette layer will still be honored, but 
its appearance won't be quite as distinctive. 


Changing the JDesktopicon 


The JInternalFrame relies on an inner class, JDesktopIcon, to provide a UI delegate for the 
iconified view ofthe JInternalFrame. The class is merely a specialized JComponent for providing 
this capability, not a specialized Icon implementation, as the name might imply. In fact, the 
JDesktopIcon class comments say that the class is temporary, so you shouldn't try to customize 
it directly. (Of course, the class has been around for some time now.) 

If you do want to customize the JDesktopIcon, you can change some of the UlResource- 
related properties. Table 8-13 lists the eight UIResource-related properties forthe JDesktopIcon 
component. 
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Table 8-13. JInternalFrame.DesktoplIcon UlResource Elements 


Property String Object Type 
DesktopIcon.background Color 
DesktopIcon.border Border 
DesktoplIcon. font Font 
DesktoplIcon. foreground Color 
DesktopIcon.icon Icon 
DesktoplIcon.width Integer 
DesktopIcon.windowBindings Object[ ] 
DesktopIconUI String 
JDesktopPane Class 


Another class for working with groups of internal frames is the JDesktopPane class. The sole 
purpose of the desktop pane is to contain a set of internal frames. When internal frames are 
contained within a desktop pane, they delegate most of their behavior to the desktop manager 
ofthe desktop pane. You'll also learn about the DesktopManager interface in greater detail later 
in this chapter. 


Creating a JDesktopPane 


The JDesktopPane has a single no-argument constructor. Once it's created, you'd typically 
place the desktop in the center of a container managed by a BorderLayout. This ensures that 
the desktop takes up all the room in the container. 


Adding Internal Frames to a JDesktopPane 


The JDesktopPane doesn'timplement RootPaneContainer. Instead of adding components to the 
different panes within a JRootPane, you add them directly to the JDesktopPane: 


desktop.add(anInternalFrame); 


JDesktopPane Properties 


As Table 8-14 shows, there are eight properties of JDesktopPane. The JInternalFrame at index 0 
ofthe allFrames property array is the internal frame in front ofthe desktop (JInternalFrame f 
= desktop.getAllFrames()[0]). Besides getting all the frames within the JDesktopPane, you can 
get only those within a specific layer: public JInternalFrame[] getAllFramesInLayer(int layer). 
(Remember JLayeredPane, covered earlier in this chapterin the “Working with Component Layers 
and Positions” section, the parent class of JDesktopPane?) 

Valid dragMode property settings are the LIVE_DRAG_MODE and OUTLINE_DRAG_MODE constants 
of the class. 
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Table 8-14. JDesktopPane Properties 


Property Name Data Type Access 
accessibleContext AccessibleContext Read-only 
allFrames JInternalFrame[ ] Read-only 
desktopManager DesktopManager Read-write 
dragMode int Read-write bound 
opaque boolean Read-only 
selectedFrame JInternalFrame Read-write 

UI DesktopPaneUI Read-write 
UlClassID String Read-only 


Note There is also a special client property (JDesktopPane.. dragMode) for configuring the drawing 
mode when dragging an internal frame around. The client property has been replaced by the speedier 
versions available with the standard property. 


Customizing a JDesktopPane Look and Feel 


Back in Figure 8-5 you can see JInternalFrame objects within a JDesktopPane. The basic appear- 
ance of JDesktopPane is the same in each look and feel. As Table 8-15 shows, there aren't many 
UlResource-related properties for a JDesktopPane to configure. 


Table 8-15. JDesktopPane UlResource Elements 


Property String Object Type 
desktop Color 
Desktop.ancestorInputMap InputMap 
Desktop .background Color 

Desktop .windowBindings Object[ ] 
DesktopPane.actionMap ActionMap 
DesktopPaneUl String 


Complete Desktop Example 


Now that you have the major desktop-related classes under your belt, let's look at a complete 
desktop example. The basic process involves creating a group of JInternalFrame objects and 

putting them in a single JDesktopPane. Event handling can be done for individual components 
on each of the internal frames, if desired, or for individual frames. In this example, simply use 
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the InternalFramelconifyListener class, presented earlier in Listing 8-5, to listen for internal 
frames being iconified and deiconified. 

Figure 8-6 shows how the program looks when it first starts. One particular internal frame 
has been designated a palette, and the outline drag mode is enabled. 

The complete source for the example is shown in Listing 8-6. 


Listing 8-6. Mixing JInternalFrames and the JDesktopPane 


import javax.swing.*; 
import javax.swing.event.*; 
import java.awt.*; 

import java.awt.event.*; 


public class DesktopSample £ 


public static void main(final String[] args) 1 
Runnable runner = new Runnable() f 
public void run() £ 
String title = (args.length==0 ? "Desktop Sample" : args[o0]); 
JFrame frame = new JFrame(title); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


JDesktopPane desktop = new JDesktopPane(); 

JInternalFrame internalFrames[] = 4 
new JInternalFrame("Can Do A11", true, true, true, true), 
new JInternalFrame("Not Resizable", false, true, true, true), 
new JInternalFrame("Not Closable", true, false, true, true), 
new JInternalFrame("Not Maximizable", true, true, false, true), 
new JInternalFrame("Not Iconifiable", true, true, true, false) 


1e 


( 
( 
( 
( 


InternalFrameListener internalFrameListener = 
new InternalFramelconifyListener(); 


int pos = 0; 

for(JInternalFrame internalFrame: internalFrames) ( 
// Add to desktop 
desktop.add(internalFrame); 


// Position and size 
internalFrame.setBounds(pos*25, pos*25, 200, 100); 
pos++; 


// Add listener for iconification events 
internalFrame.addInternalFrameListener(internalFramelistener); 


Jlabel label = new JLabel(internalFrame.getTitle(), JLabel.CENTER); 
internalFrame.add(label, BorderLayout.CENTER); 


J 


$; 


EventQueue.invokeLater(runner); 


y 
J 
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// Make visible 
internalFrame.setVisible(true); 


J 


JInternalFrame palette = 


new 


JInternalFrame("Palette", true, false, true, false); 


palette.setBounds(350, 150, 100, 100); 
palette.putClientProperty("JInternalFrame.isPalette", Boolean.TRUE); 
desktop.add(palette, JDesktopPane.PALETTE_ LAYER); 
palette.setVisible(true); 


desktop.setDragMode(JDesktopPane.OUTLINE_DRAG_MODE); 


frame. 
frame. 
frame. 


add(desktop, BorderLayout.CENTER); 
setSize(500, 300); 
setVisible(true); 


DesktopManager Interface 


One remaining piece of the puzzle for working on a desktop is the desktop manager, which is 
an implementation of the DesktopManager interface, shown here: 


public interface DesktopManager ( 


publ 
publ 
publ 
publ 
publ 
publ 
publ 
publ 
publ 
publ 
publ 
publ 
publ 
publ 
int nenHeight); 
publ 


ic 
ic 
ic 
ic 
ic 
ic 
ic 
ic 
ic 
ic 
ic 
ic 
ic 
ic 


void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 


activateFrame(JInternalFrame frame); 
beginDraggingFrame(JComponent frame); 
beginResizingFrame(JComponent frame, int direction); 
closeFrame(JInternalFrame frame); 
deactivateFrame(JInternalFrame frame); 
deiconifyFrame(JInternalFrame frame); 
dragFrame(JComponent frame, int newX, int newY); 
endDraggingFrame(JComponent frame); 
endResizingFrame(JComponent frame); 
iconifyFrame(JInternalFrame frame); 
maximizeFrame(JInternalFrame frame); 
minimizeFrame(JInternalFrame frame); 
openFrame(JInternalFrame frame); 
resizeFrame(JComponent frame, int newX, int newY, int newWidth, 


lic void setBoundsForFrame(JComponent frame, int newX, int newY, int newWidth, 
int nenHeight); 
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Note For the DesktopManager methods that accept a JComponent argument, the arguments are 
usually a JInternalFrame or another lightweight Swing component. 


When JInternalFrame objects are in a JDesktopPane, they shouldn't attempt operations 
such as iconifying or maximizing themselves. Instead, they should ask the desktop manager of 
the desktop pane in which they're installed to perform the operation: 


getDesktopPane().getDesktopManager().iconifyFrame(anInternalFrame); 


The DefaultDesktopManager class provides one such implementation of a DesktopManager. 
Tf the default isn't sufficient, a look and feel might provide its own DesktopManager implemen- 
tation class, as the Windows look and feel does with the WindowsDesktopManager. You can also 
define your own manager, but this usually isn't necessaty. 


Summary 


In this chapter, you explored the JRootPane class and how implementers ofthe RootPaneContainer 
interface rely on a JRootPane for internal component management. You also learned how in Swing 
you work with the JRootPane of a JFrame, JDialog, Jwindow, JApplet, or JInternalFrame class. 
The root pane can then layer components with the help of a JLayeredPane in such a way that 
tooltip text and pop-up menus will always appear above their associated components. 

The JInternalFrame can also reside within a desktop environment, in which a JDesktopPane 
and DesktopManager manage how and where the internal frames act and appear. You can also 
respond to internal frame events by associating InternalFrameListener implementations with 
a JInternalFrame. 

In Chapter 9, you”ll examine the specialized pop-up components within the Swing libraries: 
JColorChooser, JFileChooser, JOptionPane, and ProgressMonitor. 


CHAPTER 9 


Pop-Ups and Choosers 


l. Chapter 8, you looked at the top-level containers such as JFrame and JApplet. In addition, 
you explored the JDialog class used to create pop-up windows to display messages or get user 
input. Although the JDialog class works perfectly well, the Swing component set also offers 
several simpler approaches to get user input from pop-up windows, which you will explore in 
this chapter. 

The JOptionPane class is useful for displaying messages, obtaining textual user input, or 
getting the answer to a question. The ProgressMonitor and ProgressMonitorInputStream 
classes enable you to monitor the progress of lengthy tasks. In addition, the JColorChooser and 
JFileChooser classes come equipped with feature-filled pop-up windows for getting a color 
choice from a user or getting a file or directory name. By using these additional classes, your 
user interface development tasks can be accomplished much more quickly and easily. 


JOptionPane Class 


JOptionPane is a special class for creating a panel to be placed in a pop-up window. The purpose 
ofthe panel is to display a message to a user and get a response from that user. To accomplish 
its task, the panel presents content in four areas (see Figure 9-1): 


+ Icon: The icon area is for the display of an Icon to indicate the type of message being 
displayed to the user. It's the responsibility of the installed look and feel to provide 
default icons for certain types of messages, but you can provide your own if you need 
to display another icon type. 


+. Message: The primary purpose of this area is to display a text message. In addition, the 
area can contain any optional set of objects to make the message more informational. 


+ Input: The input area allows a userto provide a response to a message. The response can 
be free form, in a text field, or from a pick listin a combo box or list control. For yes or no 
type questions, the button area should be used instead. 


+ Button: The button area is also for getting user input. Selection of a button in this area 
signals the end of the usage of the JOptionPane. Default sets of button labels are available, 
or you can display any number of buttons, including none, with any labels you desire. 


267 


268 


CHAPTER 9 POP-UPS AND CHOOSERS 


Icon 


Selert a Destination 


6) Where would you like to go to lunch? 
Taco Bell ly 


Message 


Input Area 


Button Area 


Figure 9-1. JOptionPane parts 


All the areas are optional (although having a panel without at least a message and a button 
makes the option pane virtually useless). 

Besides being a panel with four sections within a pop-up window, the JOptionPane is 
capable of automatically placing itselfin a pop-up window and managing the acquisition of 
the user's response. It can place itselfin either a JDialog ora JInternalFrame, depending on the 
type of GUI you're providing to the user. With the help of an Icon and set of JButton components, 
the JOptionPane can easily be configured to show a variety of messages and input dialogs. 


Note Because the JOptionPane can automatically place itself in a JDialog, you might never need to 
create a JDialog directly. 


Creating a JOptionPane 


You can either manually create a JOptionPane through one ofits 7 constructors or go through 
one of the 25 factory methods discussed later in the chapter, in the “Automatically Creating a 
JOptionPane in a Pop-Up Window” section. You have the most control when manually creating the 
JOptionPane. However, you then must place itin a pop-up window, show the window, and 
finally manage getting the response. 

Because of the ease of use provided by the methods that do everything automatically, you 
might think you would only use the factory methods when working with JOptionPane. However, 
throughout this chapter, you'll discover several other reasons why you might want to do things 
manually. In addition, when you use a visual-programming environment, the environment 
treats the JOptionPane as a JavaBean component and will ignore the factory methods. 

For the seven constructors, you can have different permutations of six different arguments. 
The arguments allow you to configure something in one of the four different areas shown in 
Figure 9-1. The six arguments are the message, the message type, an option type, anicon, an 
array of options, and an initial option setting. The use of these arguments is shared with the 
factory methods. 

Let's first look at the seven constructors, and then explore the different arguments. Notice 
that the constructor arguments are cascading and only add additional arguments to the 
previous constructor. 
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public JOptionPane() 
JOptionPane optionPane = new JOptionPane(); 


public JOptionPane(Object message) 
JOptionPane optionPane = new JOptionPane("Printing complete"); 


public JOptionPane(Object message, int messageType) 
JOptionPane optionPane = new JOptionPane("Printer out of paper", 
JOptionPane. WARNING MESSAGE); 


public JOptionPane(Object message, int messageType, int optionType) 
JOptionPane optionPane = new JOptionPane("Continue printing?", 
JOptionPane.QUESTION MESSAGE, JOptionPane.YES NO OPTION); 


public JOptionPane(Object message, int messageType, int optionType, 
Icon icon) 

Icon printerIcon = new Imagelcon("printer.jpg"); 

JOptionPane optionPane = new JOptionPane("Continue printing?", 
JOptionPane.QUESTION MESSAGE, JOptionPane.YES NO OPTION, printerIcon); 


public JOptionPane(Object message, int messageType, int optionType, Icon icon, 
Object options[ ]) 

Icon greenIcon = new DiamondIcon(Color.GREEN); 

Icon redIcon = new DiamondIcon(Color.RED); 

Object optionArray[] = new Object[] [ greenIcon, redIcon) ; 

JOptionPane optionPane = new JOptionPane("Continue printing?", 
JOptionPane.O0UESTION MESSAGE, JOptionPane.YES_NO OPTION, printerlcon, 
optionArray); 


public JOptionPane(Object message, int messageType, int optionType, Icon icon, 
Object options[], Object initialValue) 

JOptionPane optionPane = new JOptionPane("Continue printing?", 
JOptionPane.O0UESTION MESSAGE, JOptionPane.YES_NO OPTION, printerIcon, 
optionArray, redIcon); 


The JOptionPane Message Argument 


The message argument is an Object, nota String. While you normally pass only a quoted string 
as this argument, with an Object argument, you can basically display anything you want in the 
message area. In the “Understanding the Message Property,” section later in this chapter, you'll 
look at the more advanced uses of this argument. Briefly, though, there are four basic rules to 
interpret the meaning of an Object -typed message argument. For elements within the Object, 
recursively follow these rules: 
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+ Ifthe message is an array of objects (Object[ ]), make the JOptionPane place each entry 
onto a separate row. 


» Ifthe message is a Component, place the component in the message area. 


+ Ifthe message is an Icon, place the Icon within a JLabel and display the label in the 
message area. 


» Ifthe message is an Object, convert itto a String with toString(), place the String in a 
JLabel, and display the label in the message area. 


The JOptionPane Message Type and Icon Arguments 


The messageType constructor argument is used to represent the type of message being displayed 
within the JOptionPane. Ifyou don't provide a custom icon for the JOptionPane, the installed 
look and feel will use the messageType argument setting to determine which icon to display 
within the icon area. Five different message types are available as JOptionPane constants: 


+ ERROR_MESSACE for displaying an error message 

+ INFORMATION MESSACE for displaying an informational message 
+ QUESTION MESSACE for displaying a query message 

+ WARNING_MESSACE for displaying a warning message 

+ PLAIN MESSACE for displaying any other type of message 


If you're using a constructor with both messageType and icon arguments and want the 
JOptionPane to use the default icon for the messageType, just specify null as the value for the 
icon argument. If the icon argument is non-null], the specified icon will be used, no matter 
what the message type is. 

Ifthe messageType constructor argument isn't specified, the default message type is 
PLAIN_MESSACE. 


The JOptionPane Option Type Argument 


The optionType constructor argument is used to determine the configuration for the set of 
buttons in the button area. Ifone ofthe options argument described nextis provided, then the 
optionType argument is ignored and configuration for the set of buttons is acquired from the 
options argument. Four different option types are available as JOptionPane constants: 


+ DEFAULT_OPTION for a single OK button 

+ OK_CANCEL_OPTION for OK and Cancel buttons 

+ YES NO CANCEL_OPTION for Yes, No, and Cancel buttons 
+ YES _NO_OPTION for Yes and No buttons 


Ifthe optionType constructor argument isn't specified, the default option type is 
DEFAULT_OPTION. 
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The JOptionPane Options and Initial Value Arguments 


The options argument is an Object array used to construct a set of JButton objects for the 
button area of the JOptionPane. Ifthis argumentis null (or a constructor without this argument 
is used), the button labels will be determined by the optionType argument. Otherwise, the array 
works similarly to the message argument, but without supporting recursive arrays: 


+ Ifan options array element is a Component, place the component in the button area. 


+ Ifan options array elementis an Icon, place the Icon within a JButton and place the 
button in the button area. 


+ Ifanoptions array elementis an Object, convertitto a String with toString(), place the 
String in a JButton, and place the button in the button area. 


Normally, the options argument will be an array of String objects. You may want to have 
an Icon on the JButton, although the resulting button won't have a label. If you want to have 
both an icon and a text label on the button, you can manually create a JButton and place it in 
the array. Alternatively, you can directly include any other Component within the array. There's 
one minor problem with these latter two approaches, however. It's your responsibility to 
handle responding to component selection and tell the JOptionPane when the user selects this 
component. The “Adding Components to the Button Area” section later in this chapter shows 
how to properly handle this behavior. 

When the options argument is non-null, the initialValue argument specifies which of 
the buttons will be the default button when the pane is initially displayed. Ifit's null, the first 
component in the button area will be the default button. In either case, the first button will 
have the input focus, unless there is an input component in the message area, in which case, 
the input component will have the initial input focus. 


Tip To have no buttons on the option pane, pass an empty array as the options setting: new Object[] Y ). 


Displaying a JOptionPane 
After you've created the JOptionPane with one of the constructors, what you have is a panel 
filled with components. In other words, the obtained JOptionPane is not yetin a pop-up window. 
You need to create a JDialog, a JInternalFrame, or another pop-up window, and then place the 
JOptionPane within that. In addition, if you pick this manual style of JOptionPane construction, 
you need to handle the closing ofthe pop-up window. You must listen for selection ofa component 
in the button area, and then hide the pop-up window after selection. 

Because there is so much to do here, the JOptionPane includes two helper methods to 
place a JOptionPane within either a modal JDialog or a JInternalFrame and take care of all the 
previously described behavior: 
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public JDialog createDialog(Component parentComponent, String title) 


public JInternalFrame createInternalFrame(Component parentComponent, String title) 


Note When using the createDialog() and createInternalFrame() methods to create a pop-up 
window, selection of an automatically created button results in the closing of the created pop-up. You would 
then need to ask the JOptionPane which option the user selected with getValue() and, if appropriate, get 
the input value with getInputValue(). 


The first argument to the methods is a component over which the pop-up window will be 
centered. The second argument is the title for the pop-up window. Once you create the pop-up 
window, whether it's a JDialog or JInternalFrame, you showit. The pop-up is then closed after 
one of the components in the button area is selected, at which point, your program continues. 
The following lines of source code show the creation of one such JOptionPane shown within a 
JDialog. The resulting pop-up window is shown in Figure 9-2. 


JOptionPane optionPane = new JOptionPane("Continue printing?", 
JOptionPane.QUESTION MESSAGE, JOptionPane.YES NO OPTION); 

JDialog dialog = optionPane.createDialog(source, "Manual Creation"); 

dialog.setVisible(true); 


Manual Creation xj 


Y Continue printing? 


Cu] 


Figure 9-2. Sample JOptionPane in a JDialog 


After you create the JOptionPane, place itin a pop-up window, and showit, and the user 
has responded, you need to find out what the user selected. The selection is provided via the 
public Object getValue() method of JOptionPane. The value returned by getValue() is 
determined by whether an options array was provided to the JOptionPane constructor. If you 
provide the array, the argument selected will be returned. Ifyou don't provide the array, an 
Integer object is returned, and its value represents the position of the button selected within 
the button area. In another case, getValue() could return null if nothing was selected, such as 
when the JDialog is closed by selecting the appropriate window decoration from the title bar 
of the pop-up window. 
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To make this multifaceted response easier to grasp, Listing 9-1 shows an OptionPaneUtils class 
that defines the method public static int getSelection(JOptionPane optionPane). Given an 
option pane, this method returns the position ofthe selected value as an int, whether or not an 
options array was provided. To indicate that nothingwas selected, JOptionPane.CLOSED_OPTION (-1) 
is returned. 


Listing 9-1. JOptionPane Utility Class 


import javax.swing.*; 
public final class OptionPaneUtils f 


private OptionPaneUtils() ( 
y 


public static int getSelection(JOptionPane optionPane) ( 
// Default return value, signals nothing selected 
int returnValue = JOptionPane.CLOSED_OPTION; 


// Get selected value 
Object selectedValue = optionPane.getValue(); 
// Tf none, then nothing selected 
if (selectedValue != null) £ 
Object options[] = optionPane.getOptions(); 
if (options == null) ( 
// Default buttons, no array specified 
if(selectedValue instanceof Integer) ( 
returnValue = ((Integer)selectedValue).intValue(); 
) 
+ else [ 
// Array of option buttons specified 
for (int i=0, n = options.length; 1 < n; i++) ( 
if(options[i].equals(selectedValue)) f 
returnValue = i; 
break; // out of for loop 
l 
) 
J 
) 
return returnValue; 


J 
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With the help of this new OptionPaneUtils.getSelection(JOptionPane) helper method, 
you can now find out the option pane selection with one line of code, and then act accordingly 
based on the response. 


int selection = OptionPaneUtils.getSelection(optionPane); 
switch (selection) ( 


break; 
default: ... 


Ifyou create a JOptionPane with a null options array, you can use the constants within the 
JOptionPane class to indicate the position of the default button labels and their return values 
from the OptionPaneUtils.getSelection(JOptionPane) method. These constants are listed in 
Table 9-1. Using these constants enables you to avoid hard-coding constants such as 0, 1, 2, or-1. 


Table 9-1. JOptionPane Option Position Constants 


Position Description 

CANCEL_OPTION.— Usedwhen the Cancel button is pressed 
CLOSED_OPTION Used when the pop-up window closed without the user pressing a button 
NO_OPTION Used when the No button is pressed 

OK_OPTION Used when the OK button is pressed 

YES OPTION Used when the Yes button is pressed 


Automatically Creating a JOptionPane in a Pop-Up Window 


You can manually create a JOptionPane, place itin a JDialog or JInternalFrame (or any other 
container), and fetch the response. Alternatively, you could use the JOptionPane factory methods 
for creating JOptionPane components directly within either a JDialog or a JInternalFrame. Using 
the many factory methods, you can create the option pane, place it in a pop-up window, and 
get the response with a single line of source code. 

There are 25 methods, which are first broken down into two sets: those that create the 
JOptionPane and show it within a JDialog and those that show the pane within a JInternalFrame. 
Methods that show the JOptionPane within a JInternalFrame are named showInternalXWXDialog(), 
and methods that create the pane within a JDialog are named shonXXXDialog(). 

The second grouping of factory methods for JOptionPane is what fills in the XXX part of the 
method names. This represents the various message types of option panes that you can create 
and display. In addition, the message type defines what is returned after the user selects some- 
thing in the option pane. The four different message types are as follows: 
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+ Message: With a message pop-up, there's no return value. Therefore, the method is defined 
void show[ Internal ]MessageDialog(...). 


+ Tnput: With an input pop-up, the return value is either what the user typed in a text field 
(a String) or what the user picked from a list of options (an Object). Therefore, the 
show[ Internal] InputDialog(...) methods return either a String or Object, depending 
on which version you use. 


+ Confirm: With the confirm pop-up, the return value signifies which, if any, button the 
user picked within the option pane. After a button is picked, the pop-up window is 
dismissed, and the returned value is one of the integer constants shown in Table 9-1. 
Therefore, the method here is defined as int show[Internal]ConfirmDialog(...). 


+ Option: With the option pop-up, the return value is an int, the same type as the confirm 
pop-up, so the methods are defined int show[ Internal ]OptionDialog(...). Ifthe 
button labels are manually specified with a non-null argument, the integer represents 
the selected button position. 


The information in Table 9-2 should help you understand the 25 methods and their argu- 
ments. The method names (and return types) are found on the left side of the table, and their 
argument lists (and data types) are on the right. The numbers that repeat across the columns 
for each method name indicate a specific set of arguments for that method. For instance, the 
showInputDialog row shows a 3 in the Parent Component column, Message column, Title 
column, and Message Type column. Therefore, the showInputDialog method has one version 
defined like this: 


public static String showInputDialog(Component parentComponent, Object message, 
String title, int messageType) 


Note With the exception of two of the showInputDialog() methods, the parent component argument 
is required for all method varieties. The message argument is the only one required for all without exception. 
What good is a pop-up dialog without a message? 


With the way the different showXXXDialog() methods are defined, you don't need to bother 
with discovering the selected button yourself, or even the user input. The return value for the 
various methods is one of the following: nothing (void return type), an int from Table 9-1, a 
String, or an Object, depending on the type of dialog box shown. 


Caution There is a significant difference between the JOptionPane constructors and the factory 
methods: The option type and message type arguments are reversed. 
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Table 9-2. JOptionPane Static create and show Methods 


Method Name/Return Type Parent Message Title Option Message 
Component Object String  Typeint  Typeint 
Component 

shonMessageDialog 123 123 23 23 

Return type: void[123] 

showInternalMessageDialog 123 123 23 23 

Return type: void[123] 

showConfirmDialog 1234 1234 234 234 34 

Return type: int[1234] 

showInternalConfirmDialog 1234 1234 234 234 34 

Return type: int 

showInputDialog 2345 123456 34 34 

Return type: String[12356]/0bject[4] 

showInternalInputDialog 123 123 23 23 

Return type: String[12]/Object[3] 

show0ptionDialog 1 1 1 1 1 

Return type: int[1] 

showInternal0ptionDialog 1 1 1 1 1 


Return type: int[1] 


JOptionPane Arguments for Factory Methods 


Almost all the arguments for the factory methods match the JOptionPane constructor arguments. 
Two lists in the “Creating a JOptionPane” section earlier in this chapter describe the acceptable 
values for the message type and option type arguments. In addition, the usage of the message, 
options, and initial value arguments are also described. The parent component and title 
argument are passed along to one of the createDialog() or createlnternalFrame() methods, 
depending on the type of pop-up in which the JOptionPane is embedded. 

You next need to consider the selection values argument and the initial selection value 
argument ofthe showInputDialog() method. With an input dialog box, you can ask the user for 
text input and allow the user to type in anything, or you can present the user with a list of 
predefined choices. The selection values argument to showInputDialog() determines how you 
provide that set of choices. The initial selection value represents the specific option to be chosen 
when the JOptionPane first appears. The look and feel will determine the appropriate Swing 
component to be used based on the number of choices presented. For small lists, a JComboBox 
is used. For larger lists, starting at 20 with the Motif, Metal/Ocean, and Windows look and feel 
types, a JList is used. 
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Table 9-2. JOptionPane Static create and show Methods (Continued) 


2 ieomicon Options IitialValue Selection Values  InitialSelection 
Object[ ] Object Object[ ] Object 

3 

3 

4 

4 

4 4 456 

3 3 3 

1 1 1 

1 1 1 


Note When the parent component argument is nul1, a hidden frame is used and the pop-up is centered 
on the screen. See the getSharedOwnerFrame() method of SwingUtilities for more details on the 
hidden frame. There are other focus-related usability issues that you might run into when specifying null as 
a parent component, if the hidden frame and dialog box are swapped to the background. 


Message Pop-Ups 


The showMessageDialog() and showInternalMessageDialog() methods create an 
INFORMATION_MESSAGE pop-up with the pop-up title “Message,” unless different argument 
settings are specified for the message type and window title. Because the sole purpose of the 
message dialog box is to display a message, these dialog boxes provide only an OK button and 
return no value. Figure 9-3 shows sample message pop-ups created from the following lines 
of source: 


JOptionPane.showMessageDialog(parent, "Printing complete"); 
JOptionPane.showInternalMessageDialog(desktop, "Printing complete"); 
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xl E message 
Mm E 
GH Printing complete ! Printing complete 


Dialog Internal Frame 


Figure 9-3. Sample JOptionPane message pop-ups 


Confirm Pop-Ups 


The shonConfirmDialog() and showInternalConfirmDialog() methods, by default, create a 
pop-up with a QUESTION_MESSAGE type and the pop-up title “Select an Option.” Because confirm 
dialog boxes ask a question, their default option type is YES_NO_CANCEL_OPTION, givingthem Yes, 
No, and Cancel buttons. The return value from a call to any of these methods is one ofthe 
JOptionPane class constants YES OPTION, NO_OPTION, or CANCEL_OPTION. No prizes for guessing 
which constant maps to which option pane button! Figure 9-4 shows sample confirm pop-ups 
created from the following lines of source: 


JOptionPane.showConfirmDialog(parent, "Continue printing?"); 
JOptionPane.showInternalConfirmDialog(desktop, "Continue printing?"); 


xl El select an Option 
[2] Continue printing? 2 Continue printing? 
Yes No Cancel Yes No 


Dialog Internal Frame 


Figure 9-4. Sample JOptionPane confirm pop-ups 


Input Pop-Ups 


By default, the showInputDialog() and showInternalInputDialog() methods create a 
QUESTION_MESSAGE pop-up with an “Input” pop-up title. The option type for input dialogs is 
OK_CANCEL_OPTION, giving them an OK and a Cancel button, and the option type isn't changeable. 
The return data type for these methods is either a String or an Object. If you don't specify 
selection values, the pop-up prompts the user with a text field and returns the input as a 
String. If you do specify selection values, you get back an Object from the selection values 
array. Figure 9-5 shows some input pop-ups created from the following lines of source: 


JOptionPane.showInputDialog(parent, "Enter printer name:"); 


// Moons of Neptune 

String smallList[] = ( 
"Naiad", "Thalassa", "Despina", "Galatea", "Larissa", "Proteus", 
"Triton", "Nereid") ; 
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JOptionPane.showInternalInputDialog(desktop, "Pick a printer", "Input", 
JOptionPane.OUESTION MESSAGE, null, smallList, "Triton"); 


// Twenty of the moons of Saturn 

String biglist[] = ["Pan", "Atlas", "Prometheus", "Pandora", "Epimetheus", 
"Janus", "Mimas", "Enceladus", "Telesto", "Tethys", "Calypso", "Dione", 
"Helene", "Rhea", "Titan", "Hyperion", "lapetus", "Phoebe", "Skadi", 
"Mundilfari”); 

JOptionPane.showInputDialog(parent, "Pick a printer", "Input", 
JOptionPane.QUESTION MESSAGE, null, biglist, "Titan"); 


JText Field JComboBox 


Pick a printer 
Mimas 
Enceladus 
¡Tethys 
Telesto 
¡Calypso 
Dione 
Helene 

Rhea | 
fTitan | 
Hyperion y 


Figure 9-5. Sample JOptionPane input pop-ups 


JList 


11 


Note Itis the responsibility of the look and feel to determine the type of input component. A look and feel 
can use something other than a JTextField, JComboBox, or JList. It's just that all the system-provided 
look and feel types (from Sun) use these three components. 
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Option Pop-Ups 


The showOptionDialog() and showInternal0ptionDialog() methods provide the most flexibility 
because they allowyou to configure all the arguments. There are no default arguments, and the 
return value is an int. Ifan options argumentis not specified, the return value will be one ofthe 
constants listed in Table 9-1. Otherwise, the value returned represents the component position 
ofthe selected option from the options argument. Figure 9-6 shows a couple ofinput pop-ups 
created from the following lines of source, in which icons (instead of text) are provided on the 
buttons: 


Icon greenIcon = new DiamondIcon(Color.GREEN); 
Icon redIcon = new DiamondIcon(Color.RED); 

Object iconArray[] = ( greenIcon, redIcon) ; 
JOptionPane.showO0ptionDialog(source, "Continue printing?", "Select an Option", 
JOptionPane.YES_NO OPTION, JOptionPane.OUESTION MESSAGE, null, iconArray, 

iconArray[1]); 


Icon bluelcon = new DiamondIcon(Color.BLUE); 
Object stringArray[] = £ "Do It", "No Way") ; 
JOptionPane.showInternal0ptionDialog(desktop, "Continue printing?", 

"Select an Option", JOptionPane.YES NO OPTION, JOptionPane.QUESTION MESSAGE, 
bluelcon, stringArray, stringArray[0]); 


xl E sotectan Option 


4 
l U | Continue printing? Continue printing? 
[a] No Way 


Dialog Internal Frame 


Figure 9-6. Sample JOptionPane option pop-ups 


Caution When using a factory method to show a JOptionPane within a JDialog, the dialog box is 
automatically modal, preventing another window from getting the input focus. When showing the JOptionPane 
within a JInternalFrane, the internal frame might be modal, but other windows might not be. Therefore, 
a user could do something within one of the other windows of the application, including an action on the 
JDesktopPane. 


JOptionPane Properties 


Table 9-3 shows the 15 properties of JOptionPane. These properties are accessible only if you 
don'tuse one of the factory methods of JOptionPane. For most of the arguments, their meaning 
maps directly to one of the constructor arguments. 
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Table 9-3. JOptionPane Properties 
Property Name Data Type Access 
accessibleContext AccessibleContext  Read-only 
icon Icon Read-write bound 
initialSelectionValue Object Read-write bound 
initialValue Object Read-write bound 
inputValue Object Read-write bound 
maxCharactersPerLineCount int Read-only 
message Object Read-write bound 
messageType int Read-write bound 
options Object[] Read-write bound 
optionType int Read-write bound 
selectionValues Object[] Read-write bound 
UI OptionPaneUI Read-write bound 
UlClassID String Read-only 
value Object Read-write bound 
wantsInput boolean Read-write bound 


The wantsInput property is automatically set to true for the input dialog boxes or when the 
selectionValues property is non-null. The inputValue property is the item picked from an 
input dialog box. The value property indicates the option selected from the button area. 


Displaying Multiline Messages 


The maxCharactersPerLineCount property is setto an extremely large value, Integer.MAX_VALUE, 
by default. For some strange reason, the Swing developers chose not to provide a setter method 
for this property. Ifyou want to change the setting, you must subclass JOptionPane and override the 
public int getMaxCharactersPerLineCount() method. This causes a long text message to be 
broken up into multiple lines within an option pane. In addition, you cannot use any of the 
factory methods because they don't know about your subclass. 

To help you create narrow JOptionPane components, you can add the source shown in 
Listing 9-2 to the OptionPaneUtils class definition shown earlier in Listing 9-1. The new method 
provides a way of specifying the desired option pane character width. 
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Listing 9-2. Helper Method to Create a Narrow JOptionPane 


public static JOptionPane getNarrow0ptionPane(int maxCharactersPerLineCount) ( 
// Our inner class definition 
class Narrow0ptionPane extends JOptionPane ( 
int maxCharactersPerlineCount; 
Narrow0ptionPane(int maxCharactersPerLineCount) f 
this.maxCharactersPerLineCount = maxCharactersPerlineCount; 
J 
public int getMaxCharactersPerLineCount() ( 
return maxCharactersPerLineCount; 
1 
J 


return new NarrowOptionPane(maxCharactersPerLineCount); 


J 


Once the method and new class are defined, you can create an option pane of a specified 
character width, manually configure all the properties, place it in a pop-up window, showit, 
and then determine the user's response. The following source demonstrates using these new 
capabilities, with the long message trimmed a bit. 


String msg = "this is a really long message ... this is a really long message"; 
JOptionPane optionPane = OptionPaneUtils.getNarrow0ptionPane(72); 
optionPane.setMessage(msg); 
optionPane.setMessageType(JOptionPane.INFORMATION_ MESSAGE); 

JDialog dialog = optionPane.createDialog(source, "Width 72"); 
dialog.setVisible(true); 


Figure 9-7 demonstrates what would happen if you didn't change the 


maxCharactersPerLineCount property. Figure 9-7 also shows the new narrow JOptionPane. 


y 


8) imusts areatlylong message thés is a real long message this is a really long message tes is a 1ea8y long messago Ihés ls a rot long message thes Es a real long messago this ls a roy long message 


on 


Default 


x 


(1) this is a really long message this is a really long message this is a 
al really long message this is a really long message this is a really long 
message this is a really long message this is a really long message 


[ox ] 


Narrow 


Figure 9-7. Default JOptionPane and a narrow JOptionPane 


Although this seems like a lot of work, it's the best way to create multiline option panes, 
unless you want to manually parse the message into separate lines. 
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Note Including the characters 1 n in the message text will force the message to be displayed on multiple 
lines. Then it's your responsibility to count the number of characters in each message line. The message text 
in a JOptionPane can be formatted with HTML tags, as it can in other Swing components. 


Understanding the Message Property 


In all the previous examples in this chapter of using the message argument to the JOptionPane 
constructors and using the factory methods, the message was a single string. As described 
earlier in the “The JOptionPane Message Argument” section, this argument doesn't need to be 
a single string. For instance, ifthe argument were an array of strings, each string would be ona 
separate line. This eliminates the need to use the narrow JOptionPane, but requires you to 
count the characters yourself. However, because you're splitting apart the message, you can 
use one of the 25 factory methods. For instance, the following source creates the pop-up 
window shown in Figure 9-8. 


String multilineMsg[] = £ "Hello,", "World") ; 
JOptionPane.showMessageDialog(source, multiLineMsg); 


x 
O Hello, 
World 


Figure 9-8. Using JOptionPane with a string array 


Caution !f you manually count the characters within a long message to split it into a multiline message, 
the output may not be the best. For instance, when using a proportional font in which character widths vary, 
a line of 20 w characters would be much wider than a line of 20 ¡or / characters. 


The message argument not only supports displaying an array of strings, but it also can 
support an array of any type of object. If an element in the array is a Component, it's placed 
directly into the message area. If the elementis an Icon, the icon is placed within a JLabel, and 
the JLabel is placed into the message area. All other objects are converted to a String, placed 
into a JLabel, and displayed in the message area, unless the objectis itselfan array; in that case, 
these rules are applied recursively. 

To demonstrate the possibilities, Figure 9-9 shows offthe true capabilities ofthe JOptionPane. 
The actual content isn't meant to show anything in particular—just that you can display a lot 
of different stuff. The message argument is made up of the following array: 


Object complexMsg[] = ( 
"Above Message", new DiamondIcon(Color.RED), new JButton("Hello"), 
new JSlider(), new DiamondIcon(Color.BLUE), "Below Message") ; 
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[2] Above Message 
54 


Hello, 


: y 


+ 


Below Message 


Cancel 


Figure 9-9. Using JOptionPane with a complex message property 


Adding Components to the Message Area 


If you were to display the pop-up in Figure 9-9, you would notice a slight problem. The option 
pane doesn't know about the embedded JS1ider setting, unlike the way it automatically knows 
about input to the automatic JTextField, JComboBox, or JList components. If you want the 
JOptionPane (or for that matter, any input component) to get the JS1ider value, you need to 
have your input component change the inputValue property of the JOptionPane. When this 
value is changed, the option pane tells the pop-up window to close because the JOptionPane 
has acquired its input value. 

Attaching a ChangeListener to the JS1ider component enables you to find out when its 
value has changed. Adding yet another method to the OptionPaneUtils class shown earlier in 
Listing 9-1 allows you to reuse this specialized JS51ider with multiple JOptionPane objects more 
easily. The important method call is shown in boldface in Listing 9-3. A similar line would need 
to be added for any input component that you wanted to place within a JOptionPane. The line 
notifies the option pane when the user has changed the value of the input component. 


Listing 9-3. Helper Method for Creating a JSlider for Use in a JOptionPane 


public static JSlider getSlider(final JOptionPane optionPane) ( 
Jslider slider = new JSlider(); 
slider.setMajorTickSpacing (10); 
slider.setPaintTicks(true); 
slider.setPaintLabels(true); 
ChangeListener changelistener = new ChangeListener() ( 
public void stateChanged(ChangeEvent changeEvent) ( 
JSlider theSlider = (JSlider)changeEvent.getSource(); 
if (Itheslider.getValuelsAdjusting()) ( 
optionPane.setInputValue(new Integer(theSlider.getValue())); 
) 
) 
A 
slider.addChangeListener(changeListener); 
return slider; 


Now that the specialized JS1ider is created, you need to place iton a JOptionPane. This 
requires the manual creation of a JOptionPane component and, surprisingly, doesn't require 
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the setting ofthe wantsInput property. The wantsInput property is set to true only when you 
want the JOptionPane to provide its own input component. Because you're providing one, this 
isn't necessary. The resulting pop-up window is shown in Figure 9-10. (The JSlider component 
will be more fully described in Chapter 12.) 


JOptionPane optionPane = new JOptionPane(); 

JSlider slider = OptionPaneUtils.getSlider(optionPane); 
optionPane.setMessage(new Object[] £ "Select a value: " , slider) ); 
optionPane.setMessageType(JOptionPane.QUESTION MESSAGE); 
optionPane.setO0ptionType(JOptionPane.OK CANCEL OPTION); 

JDialog dialog = optionPane.createDialog(source, "My Slider”); 
dialog.setVisible(true); 
System.out.println ("Input: 


" 


+ optionPane.getInputValue()); 


My Slider xj 


2 Select a value: 
- = y: 


0 10 20 30 40 50 60 70 80 90100 


| Cancel 


Figure 9-10. Using JOptionPane with a JSlider 


Note !f the user doesn't move the slider, JOptionPane.. get InputValue() correctly returns 
JOptionPane.UNINITIALIZED VALUE. 


Adding Components to the Button Area 


In “The JOptionPane Options and Initial Value Arguments” section earlier in this chapter, you 
saw that if you have a Component in the array of options for the JOptionPane, you must configure 
the component yourself to handle selection. The same holds true for any components you add 
via the options property. When a component is configured to handle selection, the pop-up 
window that a JOptionPane is embedded in will disappear when the component is selected. 
The default set of buttons works this way. When installing your own components, you must 
notify the option pane when one of the components has been selected by setting the value 
property of the option pane. 

To demonstrate this mechanism, create a JButton with both an icon and a text label that 
can be placed in an option pane. Without defining this component yourself, the option pane 
supports only the display of a label or an icon on the button. When the button is selected, the 
button tells the option pane it was selected by setting the option pane's value property to the 
current text label of the button. Adding yet another method to OptionPaneUtils shown earlier 
in Listing 9-1 allows you to create such a button. The boldfaced line in the source shown in 
Listing 9-4 is the important method call to add to any other such component that you want to 
combine with the component array for the options property of a JOptionPane. The line would 
be called after selection of such a component. 
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Listing 9-4. A JButton for Use on a JOptionPane 


public static JButton getButton( 
final JOptionPane optionPane, String text, Icon icon) ( 
final JButton button = new JButton (text, icon); 
ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
// Return current text label, instead of argument to method 
optionPane.setValue(button.getText()); 
J 
A 
button.addActionListener(actionListener); 
return button; 


J 


After the specialized JButton is created, you need to place itin a JOptionPane. Unfortunately, 
this, too, requires the long form of the JOptionPane usage. The resulting pop-up window is 
shown in Figure 9-11. 


JOptionPane optionPane = new JOptionPane(); 

optionPane.setMessage("I got an icon and a text label"); 
optionPane.setMessageType(JOptionPane. INFORMATION MESSAGE); 

Icon icon = new DiamondIcon (Color.BLUE); 

JButton jButton = OptionPaneUtils.getButton(optionPane, "OK", icon); 
optionPane.setOptions(new Object[] (jButton) ); 

JDialog dialog = optionPane.createDialog(source, "Icon/Text Button"); 
dialog.setVisible(true); 


Icon/Text Button ] xj 


O | got an icon and a text label 


+ OK 


Figure 9-11. Using JOptionPane with a JButton containing a text label and an icon 


Tip Setting the value of the JOptionPane with setValue() will hide the option pane when a user selects the 
button. If you want to prevent users from closing the window without selecting a button, you can set the default 
close operation of the dialog containing the JOptionPane to JDialog.DO_NOTHING_ON_CLOSE. Then 
users won't be able to select the close icon from the window adornments. Well, they can select it; it just won't 
do anything. 


Listening for Property Changes 


The JOptionPane class defines the following 11 constants to assist with listening for bound 
property changes: 
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+ ICON PROPERTY 
+ INITIAL SELECTION VALUE PROPERTY 
+ INITIAL VALUE PROPERTY 

+ INPUT_VALUE PROPERTY 

+ MESSAGE PROPERTY 

+ MESSAGE TYPE PROPERTY 

+ OPTION TYPE PROPERTY 

+ OPTIONS PROPERTY 

+ SELECTION VALUES PROPERTY 

+ VALUE PROPERTY 

+ WANTS INPUT PROPERTY 


If you don't use the factory methods of JOptionPane, you can instead use a 
PropertyChangeListener to listen for changes to the bound properties. This would allow 
you to passively listen for changes to bound properties, instead of actively getting them 
after the change. 


Customizing a JOptionPane Look and Feel 


Each installable Swing look and feel provides a different JOptionPane appearance and set of 
default UTResource values. Figure 9-12 shows the appearance of the JOptionPane container for 
the preinstalled set of look and feel types: Motif, Windows, and Ocean. 


xl 
e Where would you like to go to lunch? x 
McDonalds £ | 
oK Cancel 
Motif Windows 
xl 
+) Where would you like to go to lunch? 
MeDonatds a 
conc] 


Ocean 


Figure 9-12. JOptionPane under different look and feel types 
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The message type ofthe JOptionPane helps determine the default icon to display in the 
icon area of the option pane. For plain messages, there are no icons. The remaining four default 
icons—for informational, question, warning, and error messages—are shown in Table 9-4 for 
the different look and feel types. 


Table 9-4. JOptionPane Icons for the Different Look and Feel Types 


Look and Feel 


Motif 


Windows 


Metal 


Ocean 


Informational 


mia 


Question 


Warning Error 


t 9 


The available set ofUTResource-related properties for a JOptionPane is shown in Table 9-5. 
For the JOptionPane component, there are 56 different properties. 


Table 9-5. JOptionPane UlResource Elements 
Property String 


OptionPane. 
OptionPane. 
OptionPane. 
OptionPane. 
OptionPane. 
OptionPane. 
OptionPane. 
OptionPane. 
OptionPane. 
OptionPane. 
OptionPane. 
OptionPane. 
OptionPane. 
OptionPane. 


OptionPane. 


actionMap 

background 

border 

buttonAreaBorder 
buttonClickThreshhold 

buttonFont 

button0rientation 

buttonPadding 
cancelButtonMnemonic 
cancelButtonText 

cancelIcon 
errorDialog.border.background 
errorDialog.titlePane.background 
errorDialog.titlePane.foreground 


errorDialog.titlePane. shadow 


Object Type 
ActionMap 
Color 
Border 
Border 
Integer 
Font 
Integer 
Integer 
String 
String 
Icon 
Color 
Color 
Color 


Color 
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Table 9-5. JOptionPane UTResource Elements (Continued) 


Property String 


OptionPane. 
OptionPane. 
OptionPane. 
OptionPane. 
OptionPane. 
OptionPane. 
OptionPane. 
OptionPane. 
OptionPane. 
OptionPane. 
0 


ptionPane. 


OptionPane. 
OptionPane. 
ptionPane. 
ptionPane. 
ptionPane. 
ptionPane. 


0 
0 
0 
0 
OptionPane. 
0 


ptionPane. 
OptionPane. 
OptionPane. 
ptionPane. 
ptionPane. 
ptionPane. 
ptionPane. 


0 
0 
0 
0 
OptionPane. 
0 


ptionPane. 
OptionPane. 
OptionPane. 
OptionPane. 
OptionPane. 


OptionPane. 


errorlcon 
errorSound 

font 

foreground 
informationIcon 
informationSound 
inputDialogTitle 
isYesLast 
essageAnchor 
essageAreaBorder 
essageFont 
essageForeground 


essageDialogTitle 


inimumSize 

noButtonMnemonic 

noButtonText 

nolcon 

okButtonMnemonic 

okButtonText 

okIcon 
uestionDialog.border.background 
uestionDialog.titlePane.background 
uestionDialog.titlePane.foreground 
uestionDialog.titlePane.shadow 


uestionlcon 


S XX O. o..o 


uestionSound 

sameSizeButtons 
separatorPadding 
setButtonMargin 

titleText 
warningDialog.border.background 


warningDialog.titlePane.background 


Object Type 
Icon 
String 
Font 
Color 
Icon 
String 
String 
Boolean 
Integer 
Border 
Font 
Color 
String 
Dimension 
String 
String 
Icon 
String 
String 
Icon 
Color 
Color 
Color 
Color 
Icon 
String 
Boolean 
Integer 
Boolean 
String 
Color 


Color 
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Table 9-5. JOptionPane UlResource Elements (Continued) 


Property String Object Type 
OptionPane.warningDialog.titlePane.foreground Color 
OptionPane.warningDialog.titlePane. shadow Color 
OptionPane.warninglcon Icon 
OptionPane.warningSound String 
OptionPane.windowBindings Object[ ] 
OptionPane.yesButtonMnemonic String 
OptionPane.yesButtonText String 
OptionPane.yesTcon Icon 
OptionPaneUI String 


One good use of the resources in Table 9-5 is for customizing default button labels to 
match the locale or language of the user. For instance, to change the four labels for the Cancel, 
No, OK, and Yes buttons into French, add the following code to your program. (You may be 
able to get the translated text from a java.util.ResourceBundle.) 


// Set JOptionPane button labels to French 
UlManager.put("OptionPane.cancelButtonText", "Annuler"); 
UlManager.put("OptionPane.noButtonText", "Non"); 
UlManager.put("OptionPane.okButtonText", "D'accord”); 
UlManager.put("OptionPane.yesButtonText", "0ui"); 


Now when you display the option pane, the buttons will have localized button labels. Of 
course, this would require translating the messages for the option pane, too. Figure 9-13 shows 
how a pop-up would look for the following line of source that asks ifthe user is 18 or older. 
Because the pop-up window title isn't a property, you must pass the title to every created 
dialog box. 


int result = JOptionPane.showConfirmDialog( 
aFrame, "Est-ce que vous avez 18 ans ou plus?", "Choisisez une option", 
JOptionPane.YES NO CANCEL OPTION); 


Choisisez une option xj 


Y Est-ce que vous avez 18 ans ou plus? 


Non Annuler 


Figure 9-13. A JOptionPane in French 
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The JOptionPane component supports localized JOptionPane button labels. Out ofthe box, 
the JOptionPane displays Chinese or Japanese button labels for the standard Yes, No, Cancel, 
and OK buttons for the appropriate locale. For instance, the left side of Figure 9-14 shows buttons 
with Japanese labels for Yes, No, and Cancel, and the right side of Figure 9-14 shows buttons with 
Japanese labels for OK and Cancel. Obviously, you would need to change the message in the 
option pane, but the buttons are set for you (assuming you have the fonts to support it). 


2 S Eso 2 Enter printer name: 
: Continue printing? a | 


LADA || AL MAL 


Figure 9-14. A JOptionPane with Japanese-language buttons 


Thankfully, the 5.0 release of the JDK includes translations for the standard JOptionPane 
(as well as the JFileChooser and JColorChooser) labels. These are available for German (de), 
Spanish (es), French (fr), Italian (it), Japanese (ja), Korean (ko), English, Swedish (sv), and 
Chinese (Simplified/zh_CN and Traditional/zh_TW). 


Tip To start the Java runtime with a different language, just set the user. language property, as in 
java -Duser.language=FR ClassName. Then, whenever you create a JOptionPane, you would get the 
French labels for Yes, No, OK, and Cancel. The button labels would be like those shown in Figure 9-14, but 
without you needing to manually do the UlManager.. put () calls. (Instead of D'accord, Sun chose to leave 
OK as 0K.) 


ProgressMonitor Class 


The ProgressMonitor class is used to report on the status of a time-consuming task. The class is 
a special Swing class that's not a GUI component, an option pane, or a JavaBean component. 
Instead, you tell the ProgressMonitor when each part of the task is done. Ifthe task is taking an 
extended length of time to complete, the ProgressMonitor displays a pop-up window like the 
one shown in Figure 9-15. 


xl 
O) Loading Progress 
Loaded 95 files 
E E 
Cancel 


Figure 9-15. ProgressMonitor sample 
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After the ProgressMonitor displays the pop-up window, the user can do one of two things. 
The user can watch the ProgressMonitor display to see how much of the task has been completed; 
when the task is done, the ProgressMonitor's display automatically disappears. Or, ifthe user 
selects the Cancel button, this tells the ProgressMonitor that the task needs to be canceled. To 
detect the cancellation, the task needs to check the ProgressMonitor periodically to see ifthe 
user canceled the task's operation. Otherwise, the task will continue. 

The pop-up window that the ProgressMonitor class displays is a JOptionPane with a 
maxCharactersPerLineCount property setting of 60, allowing the option pane to automatically 
word wrap any displayed messages. The option pane is embedded within a nonmodal JDialog 
whose title is “Progress ...”. Because the JDialog isn't modal, a user can still interact with the 
main program. The JOptionPane for a ProgressMonitor will always get an informational icon 
within its icon area. 

In addition, the message area of the option pane consists of three objects: 


+. Atthetop of the message area is a fixed message that stays the same throughout the life 
ofthe JOptionPane. The message can be a text string or an array of objects just like the 
message property of JOptionPane. 


+ Inthe middle of the message area is a note or variable message that can change as the 
task progresses. 


+ Atthe bottom of the message area is a progress bar (JProgressBar component) that fills 
as an increasing percentage of the task is completed. 


The button area ofthe option pane shows a Cancel button. 


Creating a ProgressMonitor 


When you create a ProgressMonitor, there are five arguments to the single constructor: 


public ProgressMonitor(Component parentComponent, Object message, String note, 
int minimum, int maximum) 


The first argument represents the parent component for the JOptionPane for when the 
ProgressMonitor needs to appear. The parent component is the component over which the 
pop-up window appears, and acts like the parentComponent argument for the createDialog() 
method of JOptionPane. You then provide the static and variable message parts for the message 
area ofthe JOptionPane. Either of these message parts could be null, although null means that 
this part ofthe message area will never appear. Lastly, you provide minimum and maximum values 
as the range for the progress bar. The difference between these two values represents the expected 
number of operations to be performed, such as the number of files to load or the size of a file to 
read. Normally, the minimum settingis zero, but thatisn'trequired. The number of completed 
operations determines how far the progress bar moves. 

Initially, the pop-up window isn't displayed. By default, the progress monitor checks every 
half second (500 milliseconds) to see ifthe task at hand will complete in two seconds. Ifthe task 
has shown some progress and it still won't complete in two seconds, then the pop-up window 
appears. The time to completion is configurable by changing the millisToDecideToPopup and 
millisToPopup properties of the ProgressMonitor. 

The following line ofsource demonstrates the creation ofa ProgressMonitor with 200 steps 
in the operation. A reference to the ProgressMonitor would need to be saved so that it can be 
notified as the task progresses. 
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ProgressMonitor monitor = new ProgressMonitor( 
parent, "Loading Progress", "Getting Started...", 0, 200); 


Using a ProgressMonitor 


Once you've created the ProgressMonitor, you need to begin the task whose progress is being 
monitored. As the task completes one or many steps, the ProgressMonitor needs to be notified of 
the task's progress. Notification is done with a call to the public void setProgress(int newValue) 
method, where the argument represents the progress completed thus far and the newValue 
needs to be in the minimum. . .maximum range initially specified. This progress value needs to be 
maintained outside the ProgressMonitor, because you can't ask the monitor how much progress 
has been made (no public int getProgress() method of ProgressMonitor exists). Ifthe progress 
value were maintained in a variable named progress, the following two lines would update the 
progress value and notify the ProgressMonitor. 


progress += 5; 
monitor.setProgress(progress); 


Note ¡t's possible that multiple calls to setProgress() may not advance the progress bar in the option 
pane. The changes to the progress setting must be enough to make the progress bar advance at least one 
pixel in length. For instance, if the minimum and maximum settings were zero and 2 billion, increasing the 
progress setting 1,000 times by 5 would have no visible effect on the progress bar, because the fractional 
amount would be negligible. 


The progress setting could represent the number of files loaded thus far, or the number of 
bytes read in from a file. In addition to updating the count, you should update the note to 
reflect the progress. Ifthe difference between the minimum and maximum arguments used in the 
ProgressMonitor constructor were 100, then the current progress could be viewed as a percentage 
of the task. Otherwise, the progress property merely represents the progress completed so far. 


monitor.setNote("Loaded " + progress + " files"); 


It's the responsibility of the executing task to check whether the user pressed the Cancel 
button in the ProgressMonitor dialog box. Ifthe taskis canceled, the ProgressMonitor automat- 
ically closes the dialog box, but the task must actively check for the change by adding a simple 
check at the appropriate place or places in the source: 


if (monitor.isCanceled()) f 
// Task canceled - cleanup 


+ else [ 
// Continue doing task 


en 
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Most tasks requiring a ProgressMonitor will be implemented using separate threads to 
avoid blocking the responsiveness of the main program. 

Listing 9-5 shows a program that creates a ProgressMonitor and allows you to either manually 
or automatically increase its progress property (see the following section for a description of 
this property). These tasks are handled by on-screen buttons (see Figure 9-16). Selecting the 
Start button creates the ProgressMonitor. Selecting the Manual Increase button causes the 
progress to increase by 5. Selecting the Automatic Increase button causes the progress to 
increase by 3 every 250 milliseconds (1/4 second). Pressing the Cancel button in the pop-up 
window during the automatic increase demonstrates what should happen when the operation 
is canceled; the timer stops sending updates. 


£ ProgressMonitor Sample =l0/xj 


Start 


Manual Increase 


Automatic Increase 


Figure 9-16. Main ProgressMonitor sample frame 


Note The pop-up window won't appear until some progress is shown. 


The ProgressMonitorHandler inner class at the start of Listing 9-5 is necessary to ensure 
that the ProgressMonitor is accessed only from the event thread. Otherwise, the access wouldn't 
be thread-safe in some random thread. 


Listing 9-5. Sample ProgressMonitor Usage 


import javax.swing.*; 
import java.awt.*; 
import java.awt.event.*; 


public class SampleProgress ( 
static ProgressMonitor monitor; 
static int progress; 
static Timer timer; 


static class ProgressMonitorHandler implements ActionListener ( 
// Called by Timer 
public void actionPerformed(ActionEvent actionEvent) ( 
if (monitor == null) 
return; 
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if (monitor.isCanceled()) ( 
System.out.println("Monitor canceled"); 
timer.stop(); 

y else £ 
progress += 3; 
monitor.setProgress(progress); 
monitor.setNote("Loaded " + progress + " files"); 

h 

y 
) 


public static void main(String args[]) ( 


Runnable runner = new Runnable() 4 
public void run() £ 
JFrame frame = new JFrame("ProgressMonitor Sample"); 
frame.setDefaultClose0peration(JFrame.EXIT_ON CLOSE); 
frame.setLayout(new GridLayout (0, 1)); 


// Define Start Button 
JButton startButton = new JButton ("Start"); 
ActionListener startActionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
Component parent = (Component)actionEvent.getSource(); 
monitor = new ProgressMonitor(parent, "Loading Progress", 
"Getting Started...”, 0, 200); 
progress = 0; 
J 
E 
startButton.addActionListener(startActionListener); 
frame.add(startButton); 


// Define Manual Increase Button 
// Pressing this button increases progress by 5 
JButton increaseButton = new JButton ("Manual Increase"); 
ActionListener increaseActionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
if (monitor == null) 
return; 
if (monitor.isCanceled()) ( 
System.out.println("Monitor canceled"); 
) else £ 
progress += 5; 
monitor.setProgress(progress); 
monitor.setNote("Loaded " + progress + " files"); 
) 
J 
5 
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increaseButton.addActionListener(increaseActionListener); 
frame.add(increaseButton); 


// Define Automatic Increase Button 
// Start Timer to increase progress by 3 every 250 ms 
JButton autoIncreaseButton = new JButton ("Automatic Increase"); 
ActionListener autoIncreaseActionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
if (monitor != null) £ 
if (timer == null) £ 
timer = new Timer(250, new ProgressMonitorHandler()); 
) 
timer.start(); 
Ñ 
) 
E 
autoIncreaseButton.addActionListener(autoIncreaseActionListener); 
frame.add(autoIncreaseButton); 


frame.setSize(300, 200); 
frame.setVisible(true); 


) 
5 
EventQueue.invokeLater(runner); 


J 
y 


ProgressMonitor Properties 


Table 9-6 shows the eight properties of ProgressMonitor. 


Table 9-6. ProgressMonitor Properties 


Property Name Data Type Access 
accessibleContext AccessibleContext Read-only 
canceled boolean Read-only 
maximum int Read-write 
millisToDecideToPopup int Read-write 
millisToPopup int Read-write 
minimum int Read-write 
note String Read-write 


progress int Write-only 
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The millisToDecideToPopup property represents the number of milliseconds that the 
monitor waits before deciding ifit needs to display the pop-up window. Ifthe progress property 
hasn't changed yet, the monitor waits for another increment of this time period before checking 
again. When the ProgressMonitor checks and the progress property has changed, it estimates 
whether the task will be completed in the number of milliseconds in the millisToPopup property. 
If the ProgressMonitor thinks the monitored task will complete on time, the pop-up windowis 
never displayed. Otherwise, the pop-up will display after millisToPopup milliseconds have 
passed from the time the task started. 


Caution Although technically possible, it isn't a good practice to move the minimum and maximum properties 
after the pop-up has appeared. This could result in the progress bar increasing and decreasing in an erratic 
manner. The same behavior happens if you move the progress setting in a nonlinear fashion. 


Customizing a ProgressMonitor Look and Feel 


Changing the look and feel of ProgressMonitor requires changing the appearance of both the 
JProgressBar and the JLabel, as well as the JOptionPane the ProgressMonitor uses. 
The ProgressMonitor has one UIResource-related property: 


» ProgressMonitor.progressText oftype String 


ProgressMonitorinputStream Class 


The ProgressMonitorInputStream class represents an input stream filter that uses a 
ProgressMonitor to check the progress of the reading of an input stream. If the reading is 
taking too long to complete, a ProgressMonitor appears, and the user can select the Cancel 
button in the pop-up window, causing the reading to be interrupted and the input stream to 
throw an InterruptedI0Exception. 


Creating a ProgressMonitorInputStream 


Like other filtering streams, the ProgressMonitorInputStream is created with a reference 

to the stream it needs to filter. Besides a reference to this filter, the single constructor for 
ProgressMonitorInputStream requires two arguments for its ProgressMonitor: a parent compo- 
nent and a message. As seen here, the constructor takes the ProgressMonitor arguments first: 


public ProgressMonitorInputStream( 
Component parentComponent, Object message, InputStream inputStream) 


As with the JOptionPane and ProgressMonitor, the message argument is an Object, nota 
String, so you can display an array of components or strings on multiple lines. The following 
code creates one ProgressMonitorInputStream. 
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FileInputStream fis = new FileInputStream(filename); 
ProgressMonitorInputStream pmis = 
new ProgressMonitorInputStream(parent, "Reading " + filename, fis); 


Note The minimum. . .maximum range for the ProgressMonitorInputStream ProgressMonitor is 
[0...size of stream]. 


Using a ProgressMonitorInputStream 


As with all input streams, once you've created a ProgressMonitorInputStream, you need to read 
from it. If the input stream isn't read quickly enough, the underlying ProgressMonitor causes 
the progress pop-up window to appear. Once that window appears, a user can monitor the 
progress or cancel the reading by selecting the Cancel button. Ifthe Cancel button is selected, 
an InterruptedI0Exception is thrown, and the bytesTransferred field of the exception is set to 
the number of bytes successfully read. 

Figure 9-17 shows what one ProgressMonitorInputStream pop-up might look like. For a 
little variety, the pop-up uses two JLabel components in the message, instead of just one. 


x 


O Reading: 
Component.java 


_— — AE 


Cancel 


Figure 9-17. ProgressMonitorInputStream pop-up 


Listing 9-6 shows a complete source example. The boldfaced lines are the keys to using the 
ProgressMonitorInputStream. They set up the dialog box's message and create the input stream. 
The program uses a file name specified from the command line, reads the file, and copies the 
file to standard output (the console). Ifthe file is large enough, the progress monitor will appear. 
If you press the Cancel button, the reading stops and Canceled is printed to standard error. 


Listing 9-6. ProgressMonitorInputStream Demonstration 


import java.io.*; 
import java.awt.*; 
import javax.swing.*; 


public class ProgressInputSample ( 
public static final int NORMAL =0; 
public static final int BAD_FILE = 1; 
public static final int CANCELED = NORMAL; 
public static final int PROBLEM = 2; 
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public static void main(String args[]) ( 
int returnValue = NORMAL; 
if (args.length != 1) [ 
System.err.println("Usage:"); 


System.err.println("java ProgressInputSample filename"); 


) else [ 


try ( 
FileInputStream fis = new FileInputStream(args[0]); 


JLabel filenamelabel = new JLabel(args[0], JLabel.RIGHT); 


Object message[] = [ "Reading:", filenameLabel) ; 
ProgressMonitorInputStream pmis = 


new ProgressMonitorInputStream(null, message, fis); 
InputStreamReader isr = new InputStreamReader(pmis); 


BufferedReader br = new BufferedReader(isr); 

String line; 

while ((line = br.readLine()) != null) ( 
System.out.printlin(line); 

y 

br.close(); 

Y catch (FileNotFoundException exception) ( 
System.err.println("Bad File " + exception); 
returnValue = BAD_FILE; 

) catch (InterruptedI0Exception exception) f 
System.err.println("Canceled"); 
returnValue = CANCELED; 

) catch (IOException exception) ( 
System.err.println("I/0 Exception 
returnValue = PROBLEM; 

J 


) 
// AWT Thread created - must exit 
System.exit(returnValue); 


+ exception); 


J 
J 


Note Having a null argument for the parent component to the ProgressMonitorInputStream 


constructor causes the pop-up window to appear centered on the screen. 


ProgressMonitorInputStream Properties 


Table 9-7 shows the single property of ProgressMonitorInputStream. The ProgressMonitor is 
created when the input stream is created. You shouldn't need to modify the ProgressMonitor. 
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However, you might want to provide a longer or shorter delay (the millisToDecideToPopup 
property of ProgressMonitor) before the pop-up windowis displayed. 


Table 9-7. ProgressMonitorInputStream Property 
Property Name Data Type Access 


progressMonitor ProgressMonitor Read-only 


JColorChooser Class 


You can think of a JColorChooser as an input-only JOptionPane whose input field asks you to 
choose a color. Like a JOptionPane, the JColorChooser is just a bunch of components in a 
container, not a ready-to-use pop-up window. Figure 9-18 shows how a JColorChooser might 
appear in your own application window. At the top are three selectable color chooser panels; 
at the bottom is a preview panel. The “I Love Swing” bit is not part of the chooser, but of the 
application that contains the chooser. 


Color Chooser Panel 


E IColarChooser Popup PAPES! 
Pick o 
$Swatches | 4SB_ RGB 


«E JColorChooser 


Preview Panel 


Figure 9-18. JColorChooser sample 


In addition to appearing within your application windows, the JColorChooser class also 
provides support methods for automatically placing the group of components in a JDialog. 
Figure 9-19 shows one such automatically created pop-up. 
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£: Change Button Background xj 


[Swatches | HSB [RGB | 


Cancel Reset 


Figure 9-19. JColorChooser pop-up sample 


In support of this behavior, the JColorChooser class requires the help of several support 
classes found in the javax.swing.colorchooser package. The data model for the JColorChooser 
is an implementation of the ColorSelectionModel interface. The javax.swing.colorchooser 
package provides the DefaultColorSelectionModel class as an implementation of the 
ColorSelectionModel interface. For the user interface, the JColorChooser class relies on the 
ColorChooserComponent Factory to create the default panels from which to choose a color. 
These panels are specific subclasses ofthe AbstractColorChooserPanel class, and if you don't 
like the default set, you can create your own. 

By default, when multiple chooser panels are in a JColorChooser, each panel is shown on 
a tab of a JTabbedPane. However, the ColorChooserUl can deal with multiple panels in any way 
it desires. 


Creating a JColorChooser 


If you want to create a JColorChooser and place it in your own window, you use one ofthe 
following three constructors for the JColorChooser class: 


public JColorChooser() 
JColorChooser colorChooser = new JColorChooser(); 


public JColorChooser(Color initialColor) 
JColorChooser colorChooser = 
new JColorChooser(aComponent.getBackground()); 


public JColorChooser(ColorSelectionModel model) 
JColorChooser colorChooser = new JColorChooser(aColorSelectionModel); 


By default, the initial color for the chooser is white. Ifyou don't want white as the default, 
you can provide the initial color as a Color object or ColorSelectionModel. 
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Using JColorChooser 


Once you've created a JColorChooser from a constructor, you can place itin any Container, just 
like any other Component. For instance, the source shown in Listing 9-7 created the GUI shown 
earlier in Figure 9-18. 


Listing 9-7. Using a JColorChooser in Your JFrame 


import java.awt.*; 

import javax.swing.*; 

import javax.swing.event.*; 
import javax.swing.colorchooser.*; 


public class ColorSample ( 


public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("JColorChooser Popup"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


final JLabel label = new JLabel("I Love Swing", JLabel.CENTER); 
label.setFont(new Font("Serif", Font.BOLD | Font.ITALIC, 48)); 
frame.add(label, BorderLayout.SOUTH); 


final JColorChooser colorChooser = 
new JColorChooser(label.getBackground()); 
colorChooser.setBorder ( 
BorderFactory.createTitledBorder("Pick Foreground Color")); 


// More source to come 
frame.add(colorChooser, BorderLayout.CENTER); 


frame.pack(); 
frame.setVisible(true); 
) 
5 
EventQueue.invokeLater(runner); 
) 
) 


Although this source code creates the GUI, selecting a different color within the 
JColorChooser doesn't do anything yet. Let's now look at the code that causes color changes. 
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Listening for Color Selection Changes 


The JColorChooser uses a ColorSelectionModel as its data model. As the following interface 
definition shows, the data model includes a single property, selectedColor, for managing the 
state of the color chooser. 


public interface ColorselectionModel ( 
// Listeners 
public void addChangeListener(Changelistener listener); 
public void removeChangeListener(ChangeListener listener); 
// Properties 
public Color getSelectedColor(); 
public void setSelectedColor(Color newValue); 


When a user changes the color within the JColorChooser, the selectedColor property changes, 
and the JColorChooser generates a ChangeEvent to notify any registered ChangeListener objects. 

Therefore, to complete the earlier ColorSample example in the previous section, and have 
the foreground color of the label change when the user changes the color selection within the 
JColorChooser, you need to register a ChangeListener with the color chooser. This involves 
creating a ChangeListener and adding it to the ColorSelectionModel. Placing the source code 
shown in Listing 9-8 where the //More source to come comment appears in the Listing 9-7 is 
necessary for this example to work properly. 


Listing 9-8. Activating the JColorChooser Example 


ColorSelectionModel model = colorChooser.getSelectionModel(); 
ChangeListener changelistener = new ChangeListener() ( 
public void stateChanged(ChangeEvent changeEvent) ( 
Color newForegroundColor = colorChooser.getColor(); 
label.setForeground(newForegroundColor); 
) 
y; 


model .addChangeListener(changelistener); 


Once this source is added, the example is complete. Running the program brings up 
Figure 9-18, and selecting a new color alters the foreground of the label. 


Creating and Showing a JColorChooser Pop-Up Window 


Although the previous example is sufficient if you want to include a JColorChooser within your 
own window, more often than not, you want the JColorChooser to appear in a separate pop-up 
window. This window might appear as the result of selecting a button on the screen, or possibly 
even selecting a menu item. To support this behavior, the JColorChooser includes the following 
factory method: 


public static Color showDialog(Component parentComponent, 
String title, Color initialColor) 
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When called, showDialog() creates a modal dialog box with the given parent component 
and title. Within the dialog box is a JColorChooser whose initial color is the one provided. As 
you can see in Figure 9-18 (shown earlier in the chapter), along the bottom are three buttons: 
OK, Cancel, and Reset. When OK is pressed, the pop-up window disappears and the showDialog() 
method returns the currently selected color. When Cancel is pressed, null is returned instead 
of the selected color or the initial color. Selection ofthe Reset button causes the JColorChooser 
to change its selected color to the initial color provided at startup. 

What normally happens with the showDialog() method is that the initial color argument is 
some color property of an object. The returned value of the method call then becomes the new 
setting for the same color property. This usage pattern is shown in the following lines of code, 
where the changing color property is the background for a button. As with JOptionPane, the 
null parent-component argument causes the pop-up window to be centered on the screen 
instead of over any particular component. 


Color initialBackground = button.getBackground(); 
Color background = JColorChooser.showDialog( 

null, "Change Button Background", initialBackground); 
if (background != null) ( 

button.setBackground (background); 
y 


To place this code in the context of a complete example, Listing 9-9 shows source code 
that offers a button that, when selected, displays a JColorChooser. The color selected within the 
chooser becomes the background color of the button after the OK button is selected. 


Listing 9-9. Using showDialog with the JColorChooser 


import java.awt.*; 
import java.awt.event.*; 
import javax.swing.*; 


public class ColorSamplePopup ( 


public static void main(String args[]) ( 
Runnable runner = new Runnable() £ 
public void run() ( 
JFrame frame = new JFrame("JColorChooser Sample Popup"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


final JButton button = new JButton("Pick to Change Background"); 


ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
Color initialBackground = button.getBackground(); 
Color background = JColorChooser.showDialog( 
null, "Change Button Background", initialBackground); 
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if (background != null) £ 
button.setBackground(background) ; 
j 
) 
5 
button.addActionListener(actionListener); 
frame.add(button, BorderLayout.CENTER); 


frame.setSize(300, 100); 
frame.setVisible(true); 
J 
E 
EventQueue.invokeLater(runner); 
) 
J 


Providing Your Own OK/Cancel Event Listeners 


If the showDialog() method provides too much automatic behavior, you may prefer another 
JColorChooser method that allows you to customize the chooser before displaying it and define 
what happens when the OK and Cancel buttons are selected: 


public static JDialog createDialog(Component parentComponent, String title, 
boolean modal, JColorChooser chooserPane, ActionListener okListener, 
ActionListener cancelListener) 


In createDialog(), the parent component and title arguments are the same as showDialog(). 
The modal argument allows the pop-up window to be nonmodal, unlike showDialog() in 
which the pop-up is always modal. When the pop-up is not modal, the user can still interact 
with the rest of the application. The OK and Cancel buttons in the pop-up window automati- 
cally have one associated ActionListener that hides the pop-up window after selection. It's 
your responsibility to add your own listeners if you need any additional response from selection. 

To demonstrate proper usage of createDialog(), the program shown in Listing 9-10 dupli- 
cates the functionality of the program shown in Listing 9-9. However, instead of automatically 
accepting the new color, the color change is rejected if the new background is the same color 
as the foreground. In addition, ifthe user selects the Cancel button, the button background 
color is set to red. 


Listing 9-10. Custom Action Listeners on JColorChooser Buttons 


import java.awt.*; 

import java.awt.event.*; 

import javax.swing.*; 

import javax.swing.event.*; 
import javax.swing.colorchooser.*; 


public class CreateColorSamplePopup ( 
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public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("JColorChooser Create Popup Sample"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


final JButton button = new JButton("Pick to Change Background"); 


ActionlListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
Color initialBackground = button.getBackground(); 


final JColorChooser colorChooser = 
new JColorChooser(initialBackground); 


// For okay selection, change button background to selected color 
ActionListener okActionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
Color newColor = colorChooser.getColor(); 
if (newColor.equals(button.getForeground())) 4 
System.out.println("Color change rejected"); 
j else £ 
button.setBackground(colorChooser.getColor()); 
) 
) 
$ 


// For cancel selection, change button background to red 
ActionListener cancelActionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
button.setBackground(Color.RED); 
) 
E 


final JDialog dialog = JColorChooser.createDialog(null, 
"Change Button Background", true, colorChooser, 
okActionListener, cancelActionListener); 


// Wait for current event dispatching to complete before showing 
Runnable showDialog = new Runnable() £ 
public void run() ( 
dialog.setVisible(true); 
y 
E 
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EventQueue.invokeLater(showDialog); 
J 
E 
button.addActionListener(actionListener); 
frame.add(button, BorderLayout.CENTER); 


frame.setSize(300, 100); 
frame.setVisible(true); 
) 
5 
EventQueue.invokeLater(runner); 
) 
) 


Note Notice that the actionPerformed() method that shows the color chooser uses the 
EventQueue.invokeLater() method to show the chooser. The current event handler needs to finish 
before showing the chooser. Otherwise, the previous action event processing won't complete before the 
chooser is shown. 


JColorChooser Properties 


Table 9-8 lists information on the eight properties of the JColorChooser, including the three 
data types of the single property color. 


Table 9-8. JColorChooser Properties 


Property Name Data Type Access 
accessibleContext AccessibleContext Read-only 
chooserPanels AbstractColorChooserPanel[ |] Read-write bound 
color Color Read-write 

color int rgb Write-only 

color int red, int green, int blue Write-only 
dragEnabled boolean Read-write 
previewPanel JComponent Read-write bound 
selectionModel ColorSelectionModel Read-write bound 
UI ColorChooseruI Read-write bound 


UlClassID String Read-only 
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The color property is special in that it has three ways of setting itself: 


+ Directly from a Color 


+ From one integer representing its red-green-blue values combined into one int variable 
using the nibble allocation OXAARRGGBB, where A is for alpha value (and is ignored, 
using 255 instead) 


+ From three integers, separating the red, green, and blue color components into three 
separate int variables 


Ifyou don't use shonDialog(), you can customize the JColorChooser before displaying it. 
Besides customizing the color property, which is settable in the JColorChooser constructor, 


you can customize the component to be displayed in the preview area and the color chooser 
panels. 


Changing the Preview Panel 


It's the responsibility of the ColorChooserComponentFactory class to provide the default 
component for the preview area of the JColorChooser. For the standard look and feel types, 
the preview panel is in the bottom portion of the color chooser. 

If you don't want a preview panel in the color chooser, you must change the previenPanel 
property to a component value that isn't null. When the property is set to null, the default 
preview panel for the look and feel is shown. Setting the property to an empty JPanel serves the 
purpose of not showing the preview panel. 


colorChooser.setPreviewPanel(new JPanel()); 


Figure 9-20 shows what one such color chooser might look like without the preview panel. 
Because the JPanel has no size when nothing is in it, this effectively removes the panel. 


Change Button Background ] xj 
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Figure 9-20. JColorChooser without a preview panel 


If you want the preview panel present, but just don't like the default appearance, you can 
add your own JComponent to the area. Configuration entails placing your new preview panel in 
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a title-bordered container, and having the foreground of the preview panel change when the 
user selects a new color. 


Caution A bug in the ColorChooserUl implementation class (BasicColorChooseruUl) requires an 
extra step to properly install the preview panel. Besides calling setPreviewPanel (newPanel), you must 
set the panel's size and border to enable the user interface to properly configure the new preview panel. 
The exact steps seem to vary with which JDK release you are using. See http: //bugs .sun.com/ 
bugdatabase/view_bug.do?bug_id=5029286 for more details. There are some other related bugs 
(search the Bug Parade for setPreviewPanel). 


The following source demonstrates the use ofa JLabel as the custom preview panel with 
the necessary work-around. Figure 9-21 demonstrates what the JColorChooser that uses this 
preview panel would look like. 


final JLabel previewlabel = new JLabel("I Love Swing", JLabel.CENTER); 
previewlLabel.setFont(new Font("Serif", Font.BOLD | Font.ITALIC, 48)); 
previewLabel.setSize(previewLabel.getPreferredSize()); 
previewLabel.setBorder(BorderFactory.createEmptyBorder(0,0,1,0)); 
colorChooser.setPrevienPanel (previewLabel); 


£: Change Button Background J xj 
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Figure 9-21. JColorChooser with custom preview panel 


Note Because the initial setting for the foreground of the preview panel is its background color, the panel 
will appear to be empty. This is one reason why the default preview panel shows text with contrasting back- 
ground colors. 
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Changing the Color Chooser Panels 


The various tabs in the upper part ofthe JColorChooser represent the AbstractColorChooserPanel 
implementations. Each allows the user to pick a color in a different manner. By default, the 
ColorChooserComponentFactory provides the JColorChooser with three panels (see Figure 9-22): 


+ The Swatches panel lets a user pick a color from a set of predefined color swatches, as if 
ata paint store. 


+ The HSB panel allows a user to pick a color using the Hue-Saturation-Brightness 
color model. 


The RGB panel is for picking colors using the Red-Green-Blue color model. 


xl xl 
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Figure 9-22. The default JColorChooser panels 
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Ifyou don't like the default chooser panels, or you just want to add other color chooser panels 
that work differently, you can create your own by subclassing the AbstractColorChooserPanel 
class. To add a new panel to the existing set, call the following method: 


public void addChooserPanel(AbstractColorChooserPanel panel) 
If you later decide that you no longer want the new panel, you can remove it with this method: 
public AbstractColorChooserPanel removeChooserPanel(AbstractColorChooserPanel panel) 
To replace the existing set of panels, call this method: 
setChooserPanels(AbstractColorChooserPanel panels[ ]) 


Creating a new panel entails subclassing AbstractColorChooserPanel and filling in the 
details of choosing a color for the new panel. The class definition, shown in the following code 
lines, includes five abstract methods. These five methods are what must be overridden. 


public abstract class AbstractColorChooserPanel extends JPanel ( 
public AbstractColorChooserPanel(); 
protected abstract void buildChooser(); 
protected Color getColorFromModel (); 
public ColorselectionModel getColorSelectionModel(); 
public int getDisplayMnemonicIndex(); 
public abstract String getDisplayName(); 
public abstract Icon getLargeDisplaylIcon(); 
public int getMnemonic(); 
public abstract Icon getSmallDisplayIcon(); 
public void installChooserPanel(JColorChooser); 
public void paint(Graphics); 
public void uninstallChooserPanel(JColorChooser); 
public abstract void updateChooser(); 


To demonstrate how to work with color chooser panels, let's look at how to create a new 
one that displays a list of colors from the Color and SystemColor class. From this list, the user 
must pick one. The panel will use a JComboBox to represent the list of colors. (The details of 
using a JComboBox are explained in Chapter 13.) Figure 9-23 shows the finished panel. The panel 
is created and added with the following source: 


SystemColorChooserPanel newChooser = new SystemColorChooserPanel (>; 
AbstractColorChooserPanel chooserPanels[] = (newChooser); 
colorChooser.setChooserPanels(chooserPanels); 
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Figure 9-23. Replacing all panels with the new SystemColor chooser panel 


The first method to define is public String getDisplayName(). This method returns a text 
label to display on the tab when multiple chooser panels are available. Ifthere's only one chooser 
panel, this name isn't shown. 


public String getDisplayName() Y 
return "SystemColor"; 


J 


The return values for the two Icon methods do nothing with the system look and feel types. 
You can return null from them or return an Icon to check that nothing has been done with 
them. A custom ColorChooserUl could use the two Icon methods somewhere, possibly for the 
icon on a chooser panel tab. 


public Icon getSmallDisplayIcon() ( 
return new DiamondIcon(Color.BLUE); 


J 


public Icon getLargeDisplayIcon() ( 
return new DiamondIcon(Color.GREEN); 


J 


The protected void buildChooser() methodis called bythe instal1ChooserPanel () method 
ofAbstractColorChooserPanel when the panel is added to the chooser. You use this method to 
add the necessary components to the container. In the sample SystemColorChooserPanel 
chooser, this involves creating the JComboBox and adding it to the panel. Because 
AbstractColorChooserPanel is a JPanel subclass, you can just add() the combo box. The combo 
box must be filled with options and an event handler installed for when the user selects the 
component. The specifics of the event handling are described after the following block of 
source code. 


protected void buildChooser() ( 
comboBox = new JComboBox(labels); 
comboBox.addItemListener(this); 
add(comboBox) ; 

) 
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Note In addition, if you choose to override uninstallChooserPanel (JColorChooser 
enclosingChooser), you need to call super .uninstallChooserPanel (JColorChooser 
enclosingChooser) last, instead of first. 


When a user changes the color value in an AbstractColorChooserPanel, the panel must 
notify the ColorSelectionModel of the change in color. In the SystemColorChooserPanel panel, 
this equates to the user selecting a new choice in the JComboBox. Therefore, when the combo 
box value changes, find the Color that equates to the choice and tell the model about the change. 


public void itemStateChanged(ItemEvent itemEvent) £ 
int state = itemEvent.getStateChange(); 
if (state == ItemEvent.SELECTED) f 
int position = findColorLabel(itemEvent.getItem()); 
// Last position is bad (not selectable) 
if ((position != NOT_FOUND) 88 (position != labels.length-1)) ( 
ColorSelectionModel selectionModel = getColorSelectionModel(); 
selectionModel.setSelectedColor(colors[position]); 
) 
) 
J 


The final AbstractColorChooserPanel method to implementis public void updateChooser(). 
It, too, is called by instal1ChooserPanel () at setup time. In addition, it's also called whenever 
the ColorSelectionModel of the JColorChooser changes. When updateChooser() is called, the 
chooser panel should update its display to show that the current color ofthe model is selected. 
Not all panels show which color is currently selected, so a call may do nothing. (The system- 
provided Swatches panel is one that doesn't display the current color.) In addition, it's possible that 
the current color isn't displayable on the panel. For instance, on the SystemColorChooserPanel, if 
the current selection isn'ta SystemColor or Color constant, you can either do nothing or display 
something to signify a custom color. Therefore, in the updateChooser() implementation, you 
need to get the current color from the ColorSelectionModel and change the color for the panel. 
The actual setting is done in a helper method called setColor(Color newValue). 


public void updateChooser() f 
Color color = getColorFromModel(); 
setColor(color); 


J 


The setColor(Color newColor) method simply looks up the color in a lookup table using 
the position returned from findColorPosition(Color nenColor). 


// Change combo box to match color, if possible 
private void setColor(Color newColor) ( 
int position = findColorPosition(newColor); 
comboBox.setSelectedIndex(position); 


J 
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The specifics of the findColorLabel (Object label) and findColorPosition(Color newColor) 
methods are shown in the complete source in Listing 9-11, coming up shortly. 

Ifyou don't use the shonDialog() means of showing the chooser pop-up window, once the 
chooser panel has been defined, and you've created a chooser panel, it can be placed within a 
JColorChooser with addChooserPanel(). 


AbstractColorChooserPanel newChooser = new SystemColorChooserPanel (>); 
colorChooser .addChooserPanel (newChooser); 


After showing the JColorChooser and picking the appropriate tab, your new chooser will 
be available for use, as shown in Figure 9-24. 
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Figure 9-24. After adding the new SystemColor chooser panel 


The complete source for the SystemColorChooserPanel is shown in Listing 9-11. The program 
should use the ComboBoxModel to store the labels and colors arrays of the example in one data 
model. However, the complexities of using the MVC capabilities of the JComboBox will be saved 
for Chapter 13. Feel free to change the example in order to use the appropriate data model for 
the JComboBox or some of the other Collections API classes available. 


Listing 9-11. Custom AbstractColorChooserPanel 


import javax.swing.*; 

import javax.swing.colorchooser.*; 
import java.awt.*; 

import java.awt.event.*; 


public class SystemColorChooserPanel 
extends AbstractColorChooserPanel 
implements ItemListener ( 
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private static int NOT_FOUND = -1; 


JComboBox comboBox; 
String labels[] = ( 
"BLACK", 
"BLUE", 
"CYAN", 
"DARK_GRAY”, 
"GRAY", 
"GREEN", 
"LIGHT_GRAY”, 
"MAGENTA", 
"ORANGE", 
"PINK", 
"RED", 
"WHITE", 
"YELLOW", 
"activeCaption", 
"activeCaptionBorder”, 
"activeCaptionText", 
"control", 
"controlDkShadow", 
"controlHighlight", 
"controlLtHighlight”, 
"controlShadow", 
"controlText", 
"desktop", 
"inactiveCaption", 
"inactiveCaptionBorder”, 
"inactiveCaptionText", 
"info", 
"infoText", 
"menu", 
"menuText", 
"scrollbar", 
"text", 
"textHighlight", 
"textHighlightText", 
"textInactiveText", 
"textText", 
"window", 
"windowBorder", 
"windowText", 
"<Custom>"P; 


316 CHAPTER 9 


POP-UPS AND CHOOSERS 


Color colors[] = f 


Color. 
Color. 
Color. 
Color. 
Color. 
Color. 
Color. 
Color. 
Color. 
Color. 
Color. 
Color. 
Color. 
Syste 
Systel 
Syste 
Syste 
Systel 
Systel 
Systel 
Systel 
Syste 
Systel 
Syste 
Systel 
Syste 
Systel 
Syste 
Systel 
Syste 
Systel 
Syste 
Systel 
Systel 
Systel 
Systel 
Syste 
Syste 
Systel 
null); 


BLACK, 

BLUE, 

CYAN, 

DARK_GRAY, 

GRAY, 

GREEN, 

LIGHT_GRAY, 

MAGENTA, 

ORANGE, 

PINK, 

RED, 

WHITE, 

YELLOW, 
Color.activeCaption, 
Color.activeCaptionBorder, 
Color.activeCaptionText, 
Color.control, 
Color.controlDkShadow, 
Color.controlHighlight, 
Color.controlLtHighlight, 
Color.controlShadow, 
Color.controlText, 
Color.desktop, 
Color.inactiveCaption, 
Color.inactiveCaptionBorder, 
Color.inactiveCaptionText, 
Color.info, 
Color.infoText, 
Color.menu, 
Color.menuText, 
Color.scrollbar, 
Color.text, 
Color.textHighlight, 
Color.textHighlightText, 
Color.textInactiveText, 
Color.textText, 

Color .window, 

Color .windowBorder, 
Color.windowText, 


// Change combo box to match color, if possible 


private 


void setColor(Color newColor) ( 


int position = findColorPosition(newColor); 
comboBox.setSelectedIndex(position); 


J 
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// Given a label, find the position of the label in the list 
private int findColorLabel(Object label) ( 
String stringlabel = label.toString(); 
int position = NOT_FOUND; 
for (int i=0,n=labels.length; i<n; i++) ( 
if (stringlabel.equals(labels[i])) ( 
position=i; 
break; 
J 
y 


return position; 


, 


// Given a color, find the position whose color matches 
// This could result in a position different from original if two are equal 
// Since actual color is same, this is considered to be okay 
private int findColorPosition(Color color) ( 
int position = colors.length-1; 
// Cannot use equals() to compare Color and SystemColor 
int colorrGB = color.getRGB(); 
for (int i=0,n=colors.length; i<n; i++) ( 
if ((colors[i] != null) 88 (colorrGB == colors[i].getrGB())) ( 
position=i; 
break; 
J 
y 


return position; 


. 


public void itemStateChanged(ItemEvent itemEvent) £ 
int state = itemEvent.getStateChange(); 
if (state == ItemEvent.SELECTED) 4 
int position = findColorLabel (itemEvent.getItem()); 
// last position is bad (not selectable) 
if ((position != NOT_FOUND) 88 (position != labels.length-1)) ( 
ColorSelectionModel selectionModel = getColorSelectionModel(); 
selectionModel.setSelectedColor(colors[position]); 
ñ 
) 
y 


public String getDisplayName() ( 
return "SystemColor"; 


. 
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public Icon getSmallDisplayIcon() ( 
return new DiamondIcon(Color.BLUE); 


) 


public Icon getLargeDisplayIcon() ( 
return new DiamondIcon(Color.GREEN); 


J 


protected void buildChooser() ( 
comboBox = new JComboBox(labels); 
comboBox.addItemListener(this); 
add(comboBox) ; 

y 


public void updateChooser() f 
Color color = getColorFromModel (>); 
setColor(color); 
) 
4 


Listing 9-12 demonstrates the use ofthe new chooser panel. It's a slightly modified version 
ofthe CreateColorSamplePopup program shown earlier in Listing 9-10. You can uncomment the 
setChooserPanels() statement and comment out the addChooserPanel () call to go from adding 
one panel (as in Figure 9-23) to replacing all of them (as in Figure 9-24). 


Listing 9-12. Having Custom Panels in a JColorChooser 


import java.awt.*; 

import java.awt.event.*; 

import javax.swing.*; 

import javax.swing.event.*; 
import javax.swing.colorchooser.*; 


public class CustomPanelPopup ( 


public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("JColorChooser Custom Panel Sample"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


final JButton button = new JButton("Pick to Change Background"); 
ActionListener actionListener = new ActionListener() ( 


public void actionPerformed(ActionEvent actionEvent) ( 
Color initialBackground = button.getBackground(); 


// 
// 


) 
ES 
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final JColorChooser colorChooser = 

new JColorChooser(initialBackground); 
SystemColorChooserPanel newChooser = 

new SystemColorChooserPanel(); 
AbstractColorChooserPanel chooserPanels[] = fnewChoosery; 
colorChooser.setChooserPanels(chooserPanels); 
colorChooser.addChooserPanel (newChooser); 


// For okay button, change button background to selected color 
ActionListener okActionListener = new ActionListener() f 
public void actionPerformed(ActionEvent actionEvent) ( 
Color newColor = colorChooser.getColor(); 
if (nemColor.equals(button.getForeground())) ( 
System.out.println("Color change rejected”); 
j else £ 
button.setBackground(colorChooser.getColor()); 
y 
J 
5 


// For cancel button, change button background to red 
ActionListener cancelActionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
button.setBackground(Color.RED); 
) 
5 


final JDialog dialog = 
JColorChooser.createDialog( 
null, "Change Button Background", true, colorChooser, 
okActionListener, cancelActionListener); 


// Wait for current event dispatching to complete before showing 
Runnable showDialog = new Runnable() ( 
public void run() £ 
dialog.setVisible(true); 
y 
5 


EventQueue.invokeLater(showDialog); 


button.addActionListener(actionListener); 
frame.add(button, BorderLayout.CENTER); 
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frame.setSize(300, 100); 
frame.setVisible(true); 
4 
5 
EventQueue.invokeLater(runner); 
J 
) 


Using the ColorChooserComponentFactory Class 


One class worthy of some special attention is ColorChooserComponentFactory. Normally, this 
class does its work behind the scenes, and you never need to deal with it. 

However, if you want to remove one of the default color choosers, you cannot use the 
public AbstractColorChooserPanel removeChooserPanel(AbstractColorChooserPanel panel) 
method of JColorChooser. Initially, the chooserPanels property of JColorChooser is null. When 
this property is null, the default ColorChooserUl asks the ColorChooserComponentFactory for the 
default panels with the public static AbstractColorChooserPanel[ ] getDefaultChooserPanels() 
method. So, until you modify the property, no panels will appear. If you want to remove a 
default panel, you must get the default array, place the panels you want to keep in a new array, 
and then change the chooserPanels property of the chooser to the new array. This is a little 
extra work, but it gets the job done. 

The other method inthe ColorChooserComponentFactory classis public static JComponent 
getPreviewPanel (), which gets the default preview panel when the previewPanel property ofa 
JColorChooser is null. This is the reason that providing a null argument to the setPreviewPanel () 
method of JColorChooser doesn't remove the preview panel. For the panel to be empty, you 
must provide a JComponent with no size. 


colorChooser.setPreviewPanel(new JPanel()); 


Customizing a JColorChooser Look and Feel 


The JColorChooser appearance is nearly the same for all the preinstalled look and feel types. 
The only differences are related to how each look and feel displays the internal components, 
such as a JTabbedPane, JLabel, JButton, or JSlider. Changing the UIResource-related properties 
ofthose components affects the appearance of a newly created JColorChooser. In addition, the 
JColorChooser class has its own 39 UTResource-related properties available for customization, 
as listed in Table 9-9. Most of these resources are related to text labels appearing on the various 
default color chooser panels. 


Table 9-9. JColorChooser UlResource Elements 


Property String Object Type 
ColorChooser.background Color 
ColorChooser.cancelText String 
ColorChooser. font Font 


ColorChooser.foreground Color 
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Table 9-9. JColorChooser UlResource Elements (Continued) 


Property String 


ColorChooser. 
ColorChooser. 
ColorChooser. 
ColorChooser. 
ColorChooser. 
ColorChooser. 
ColorChooser. 
ColorChooser. 
ColorChooser. 
ColorChooser. 
ColorChooser. 
ColorChooser. 
ColorChooser. 
ColorChooser. 
ColorChooser. 
ColorChooser. 
ColorChooser. 
ColorChooser. 
ColorChooser. 
ColorChooser. 
ColorChooser. 
ColorChooser. 
ColorChooser. 
ColorChooser. 
ColorChooser. 
ColorChooser. 
ColorChooser. 
ColorChooser. 
ColorChooser. 
ColorChooser. 
ColorChooser. 


ColorChooser. 


hsbBlueText 
hsbBrightnessText 
hsbDisplayedMnemonicIndex 
hsbGreenText 

hsbHueText 

hsbMnemonic 

hsbNameText 

hsbRedText 

hsbSaturationText 

okText 

panels 

previenText 

resetMnemonic 

resetText 
rgbBlueDisplayedMnemonicIndex 
rgbBlueMnemonic 

rgbBlueText 
rgbGreenDisplayedMnemonicIndex 
IgbGreenMnemonic 
IgbGreenText 

TgbMnemonic 

TgbNameText 
TgbRedDisplayedMnemonicIndex 
TgbRedMnemonic 

TgbRedText 

sampleText 
showPreviewPanelText 
swatchesDefaultRecentColor 
swatchesDisplayedMnemonicIndex 
swatchesMnemonic 
swatchesNameText 


swatchesRecentSwatchSize 


Object Type 
String 
String 
Integer 
String 
String 
Integer 
String 
String 
String 
String 
AbstractColorChooserPanel[ ] 
String 
Integer 
String 
Integer 
Integer 
String 
Integer 
Integer 
String 
Integer 
String 
Integer 
Integer 
String 
String 
Boolean 
Color 
Integer 
Integer 
String 


Dimension 
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Table 9-9. JColorChooser UlResource Elements (Continued) 


Property String Object Type 
ColorChooser.swatchesRecentText SB 
ColorChooser.swatchesSwatchSize Dimension 

ColorChooseruI String 


JFileChooser Class 


The Swing component set also provides a chooser for the selection of file names and/or direc- 
tories: the JFileChooser class. This chooser replaces the need for usingthe FileDialog from the 
original AWT component set. Like the other Swing chooser components, JFileChooser isn't 
automatically placed in a pop-up window, but it can be placed anywhere within the user interface 
of your program. Figure 9-25 shows a JFileChooser with the Metal look and feel, Ocean theme, 
that has been automatically placed in a modal JDialog. 


FileSystemView 


x 

a ; [=]|[=]| pon 
Look In: [3 jak1.5.0 y] (8/86) /(] [6010 
E] bin (A sample Py sre.zip 
(7 demo E sre y THIRDE 
docs Ty COPYRIGHT EN 
7 include Py LICENSE lidad 
Eire [Y LICENSE.rtf 
(3 lib Y README. html 
4] | [y] 
File Name: | | 
Files of Type: [All Files ly FileFilter 

Open Cancel 


Figure 9-25. JFileChooser sample 


In support of the JFileChooser class are a handful of classes in the javax. swing. filechooser 
package. The support classes include a FileFilter class for restricting files and directories to 
be listed in the FileView of the JFileChooser. The FileView controls how the directories and 
files are listed within the JFileChooser. The FileSystemViewis an abstract class that tries to hide 
file system-related operating system specifics from the file chooser. Java 2 platform vendors 
will provide operating system-specific versions so that tasks such as listing root partitions can 
be done (with 100% Pure Java code). 
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Caution Don't confuse the abstract javax.swing. filechooser. FileFilter class with the 
java.io.FileFilter interface. Although functionally similar, they're different. The two coexist because 
the java.io.FileFilter interface didn't exist in a Java 1.1 runtime. Because the original Swing 
JFileChooser needed to run in both Java 1.1 and Java 2 environments, the chooser needed to define a 
replacement. Unless otherwise specified, all FileFilter references in this text are to the class in the 
javax.swing.tfilechooser package. 


Creating a JFileChooser 


There are six constructors for JFileChooser: 


public JFileChooser() 
JFileChooser fileChooser = new JFileChooser(); 


public JFileChooser(File currentDirectory) 
File currentDirectory = new File("."); // starting directory of program 
JFileChooser fileChooser = new JFileChooser(currentDirectory); 


public JFileChooser(File currentDirectory, FileSystemView fileSystemView) 
FileSystemView fileSystemView = new SomeFileSystemView(...); 
JFileChooser fileChooser = new JFileChooser(currentDirectory, filesystemView); 


public JFileChooser(FileSystemView fileSystemView) 
JFileChooser fileChooser = new JFileChooser(fileSystemView); 


public JFileChooser(String currentDirectoryPath) 
String currentDirectoryPath = "."; // starting directory of program 


JFileChooser fileChooser = new JFileChooser(currentDirectoryPath); 


public JFileChooser(String currentDirectoryPath, FileSystemView fileSystemView) 
JFileChooser fileChooser = new JFileChooser(currentDirectoryPath, fileSystemView); 


By default, the starting directory displayed is the user's home directory (system property 
user.home). If you want to start the JFileChooser pointing at another directory, the directory 
can be specified as either a String or a File object. 

You can also specify a FileSystemView to specify a custom representation to the operating 
system's top-level directory structure. When the FileSystemView argumentis not specified, the 
JFileChooser uses a FileSystemView appropriate for the user's operating system. 


Using JFileChooser 


After creating a JFileChooser from a constructor, you can place itin any Container, because it's 
a JComponent. The JFileChooser object looks a little strange in an object that's not a pop-up 
window, but this may allow you to do a task without needing to constantly bring up a new file 
chooser. 
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Listing 9-13 demonstrates a simple window with two labels and a JFileChooser. Notice 
that there are no Open or Cancel buttons, but the buttons in the FileSystemView area are selectable. 


Listing 9-13. Using a JFileChooser in Your JFrame 


import java.io.File; 
import java.awt.*; 
import java.awt.event.*; 
import javax.swing.*; 


public class FileSamplePanel £ 


public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("JFileChooser Popup"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


final JLabel directoryLabel = new JLabel(" "); 
directoryLabel.setFont(new Font("Serif", Font.BOLD | Font.ITALIC, 36)); 
frame.add(directoryLabel, BorderLayout.NORTH); 


final JLabel filenameLabel = new JLabel(" "); 
filenameLabel.setFont(new Font("Serif", Font.BOLD | Font.ITALIC, 36)); 
frame.add(filenameLabel, BorderLayout .SOUTH); 


JFileChooser fileChooser = new JFileChooser("."); 
fileChooser.setControlButtonsAreShown(false); 
frame.add(fileChooser, BorderLayout.CENTER); 


frame.pack(); 
frame.setVisible(true); 
) 
E 
EventQueue.invokeLater(runner); 
J 
) 


Adding an ActionListener to a JFileChooser 


The JFileChooser allows you to add ActionListener objects to listen for selection ofthe approval or 
cancel actions. Approval is double-clicking a file; cancel is pressing the Escape key. To detect 
which action was triggered, check the action command for the ActionEvent received by your 
ActionListener. Its action command setting will be either JFileChooser.APPROVE_SELECTION 
for file selection or JFileChooser.CANCEL_SELECTION for pressing the Escape key. 

To complete the previous example in Listing 9-13, adding an ActionListener allows you to 
set the text for the two labels when the user selects a file. On selection, the text becomes the 
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current directory and file name. On pressing of the Escape key, text is cleared. Listing 9-14 
shows the new ActionListener. 


Listing 9-14. ActionListener for JFileChooser in Your JFrame 


// Create ActionListener 
ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
JFileChooser theFileChooser = (JFileChooser)actionEvent.getSource(); 
String command = actionEvent.getActionCommand(); 
if (command.equals(JFileChooser.APPROVE_SELECTION)) ( 
File selectedFile = theFileChooser.getSelectedFile(); 
directoryLabel.setText(selectedFile.getParent()); 
filenameLabel.setText(selectedFile.getName()); 
y else if (command.equals(JFileChooser.CANCEL_SELECTION)) ( 
directoryLabel.setText(" "); 
filenameLabel.setText(" "); 
) 
) 
5 


fileChooser.addActionListener(actionListener); 


With the addition of the ActionListener, the program is now complete in the sense that 


selection is now active. Figure 9-26 shows what this window would look like after selection of 
the COPYRIGHT file within the c:1jdk1.5.0 directory. 


£ JFileChooser Popup =10/x/ 


C:idk1.5.0 


Look In: [3 jak1.5.0 


4 


(aa (6 [a] Befs= 


($ bin E) LICENSE 

(4 demo E) LICENSE.rtf 

(4 docs [y README. html 

(E include E sre.zip 

ire [y THIRDPARTYLICENSEREADME txt 
(3 ib 

[E] sample 

E sre 

[y COPYRIGHT 


File Name: COPYRIGHT 


Files of Type: (All Files ... 


COPYRIGHT 


Figure 9-26. JFileChooser within a custom window 
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Showing a JFileChooser within a Pop-Up Window 


Instead of placing a JFileChooser panel within your own window, you will more typically place 
itina modal JDialog. There are three ways to do this, depending on the text you want to appear 
on the approval button: 


+ public int showDialog(Component parentComponent, String approvalButtonText) 
+ public int showO0penDialog(Component parentComponent) 
+ public int showSaveDialog(Component parentComponent) 


Calling one ofthese methods will place the configured JFileChooser into a modal JDialog 
and show the dialog box centered over the parent component. Providinga null parent component 
centers the pop-up window on the screen. The call doesn't return until the user selects the 
approval or cancel button. After selection of one of the two buttons, the call returns a status 
value, depending on which button was selected. This status would be one ofthree JFileChooser 
constants: APPROVE_OPTION, CANCEL_OPTION, or ERROR_OPTION. 


Caution !f the user clicks the approval button without selecting anything, CANCE L_OPTTON is returned. 


To perform the same task as the previous example, in which an ActionListener was 
attached to the JFileChooser (Listing 9-14), you can just show the dialog box and change the 
labels based on the return status, instead of relying on the action command, as follows: 


JFileChooser fileChooser = new JFileChooser("."); 

int status = fileChooser.show0penDialog(nul1); 

if (status == JFileChooser.APPROVE OPTION) ( 
File selectedFile = fileChooser.getSelectedFile(); 
directoryLabel.setText(selectedFile.getParent()); 
filenameLabel.setText(selectedFile.getName()); 

y else if (status == JFileChooser.CANCEL_OPTION) € 
directoryLabel.setText(" "); 
filenameLabel.setText(" "); 


J 


With this technique, the file chooser will be shown in another window, instead 
of within the window with the two labels. Notice that this version switches from checking 
the String return values of the earlier example to checking int return values: 
[if (command.equals(JFileChooser.APPROVE_SELECTION)) versus if (status == 
JFileChooser.APPROVE_OPTION)]. 


JFileChooser Properties 


Once you understand the basic JFileChooser usage, you can customize the component's 
behavior and appearance by modifying its many properties. Table 9-10 shows the 26 properties 
of JFileChooser. 


Table 9-10. JFileChooser Properties 


Property Name 
acceptAllFileFilter 


acceptAllFileFilterUsed 
accessibleContext 
accessory 
actionListeners 
approveButtonMnemonic 
approveButtonText 
approveButtonToolTipText 
choosableFileFilters 
controlButtonsAreShown 
currentDirectory 
dialogTitle 

dialogType 
directorySelectionEnabled 
dragEnabled 

fileFilter 
fileHidingEnabled 
fileSelectionEnabled 
fileSelectionMode 
fileSystemView 
fileView 
multiSelectionEnabled 
selectedFile 
selectedFiles 

UI 

UlClassID 


Data Type 
FileFilter 


boolean 
AccessibleContext 
JComponent 
ActionListener[ ] 
char 

String 

String 
FileFilter[ ] 
boolean 

File 

String 

int 

boolean 

boolean 
FileFilter 
boolean 

boolean 


int 


T 
pe 


FileSystemView 
FileView 


boolean 


FileChooserul 


String 
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Access 
Read-only 


Read-write bound 
Read-only 
Read-write bound 
Read-only 
Read-write bound 
Read-write bound 
Read-write bound 
Read-only 
Read-write bound 
Read-write bound 
Read-write bound 
Read-write bound 
Read-only 
Read-write 
Read-write bound 
Read-write bound 
Read-only 
Read-write bound 
Read-write bound 
Read-write bound 
Read-write bound 
Read-write bound 
Read-write bound 
Read-only 
Read-only 
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When the different showDialog() methods are used, the dialogType property is automati- 
cally set to one of three JOptionPane constants: OPEN_DIALOG, SAVE_DIALOG, CUSTOM_DIALOG. If 
you're not using showDialog(), you should set this property according to the type of dialog box you 
plan to work with. The contro1ButtonsAreShown property allows you to hide the Open, Save, 


and Cancel buttons. 


327 


328 


CHAPTER 9 POP-UPS AND CHOOSERS 


Working with File Filters 


The JFileChooser supports three ways of filtering its file and directory list. The first two involve 
working with the FileFilter class, and the last involves hidden files. First, let's look at the 
FileFilter class. 

FileFilter is an abstract class that works something like FilenameFilter in AWT. However, 
instead of working with strings for directory and file names, it works with a File object. For 
every File object that is to be displayed (both files and directories), the filter decides whether 
the File can appear within the JFileChooser. In addition to providing an acceptance mecha- 
nism, the filter also provides a description, or name, for when the description is displayed to a 
user. These two capabilities are reflected in the following two methods of the class definition: 


public abstract class FileFilter ( 
public FileFilter(); 
public abstract String getDescription(); 
public abstract boolean accept(File file); 
y 


Note Given the abstract nature of this class, it should be an interface, but it isn't. 


To demonstrate a file filter, Listing 9-15 creates one that accepts an array of file extensions. 
If the file sent to accept () is a directory, it's automatically accepted. Otherwise, the file exten- 
sion must match one of the extensions in the array provided, and the character preceding the 
extension must be a period. For this particular filter, the comparisons are case-insensitive. 


Listing 9-15. A Custom FileFilter for Use with a JFileChooser 


import javax.swing.filechooser.*; 
import java.io.File; // avoid FileFilter name conflict 


public class ExtensionFileFilter extends FileFilter ( 
String description; 
String extensions[ ]; 


public ExtensionFileFilter(String description, String extension) ( 
this(description, new String[] £ extension) ); 


) 
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public ExtensionFileFilter(String description, String extensions[]) ( 
if (description == null) ( 
// Since no description, use first extension and + of extensions as description 
this.description = extensions[0]+"( "+extensions.length+") " ; 
) else f 
this.description = description; 
) 
// Convert array to lowercase 
// Don't alter original entries 
this.extensions = (String[])extensions.clone(); 
toLower(this.extensions); 
) 
private void toLower(String array[]) ( 
for (int i=0, n=array.length; i<n; i++) ( 
array[i] = array[i].toLowerCase(); 
) 
) 


public String getDescription() ( 
return description; 


J 


// Ignore case, always accept directories 
// Character before extension must be a period 
public boolean accept(File file) £ 
if (file.isDirectory()) ( 
return true; 
) else [ 
String path = file.getAbsolutePath().toLowerCase(); 
for (int i=0, n=extensions.length; i<n; i++) ( 
String extension = extensions[i]; 
if ((path.endsWith(extension) 88 
(path.charAt (path.length()-extension.length()-1)) == '.')) ( 
return true; 
) 
J 
) 
return false; 
y 
J 
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Using the file filter entails creating it and associating it with the JFileChooser. If you just 
want to make the filter selectable by the user, but not the default initial selection, call public 
void addChoosableFileFilter(FileFilter filter). This will keep the default accept-all-files 
filter selected. If, instead, you want the filter to be set when the chooser first appears, call 
public void setFileFilter(FileFilter filter), and the file chooser will filter the initial set of 
files shown. 

For example, the following source will add two filters to a file chooser: 


FileFilter jpegFilter = 

new ExtensionFileFilter(null, new String[]( "JPG", "JPEG") ); 
fileChooser.addChoosableFileFilter(jpegFilter); 
FileFilter gifFilter = new ExtensionFileFilter("gif", new String[]([ "gif") ); 
fileChooser.addChoosableFileFilter(gifFilter); 


When no file filters have been associated with the JFileChooser, the filter from 
JFileChooser.getAcceptAllFileFilter() is used to provide a filter that accepts all files 
and that is also appropriate for the underlying operating system. 

Figure 9-27 shows an open filter selection combo box in a Motif file chooser. 


Figure 9-27. Using custom FileFilter with a JFileChooser 


CHAPTER 9 POP-UPS AND CHOOSERS 


Tip Setting the FileFilter with setFileFilter() before adding filters with add 
ChoosableFileFilter() causes the accept-all-file filter to be unavailable. To put it back, call 
setAcceptAllFileFilterUsed(true). In addition, you can reset the filter list with a call to 
resetChoosableFileFilters(). 


One built-in filterisn'ta FileFilter. It concerns hidden files, such as those that begin with 
a period (.) on UNIX file systems. By default, hidden files aren't shown within the JFileChooser. 
To enable the display of hidden files, you must set the fileHidingEnabled property to false: 


aFileChooser.setFileHidingEnabled(false); 


Tip When creating javax.swing.filechooser.FileFilter subclasses, you may want to have the 
new class also implement the java.io.FileFilter interface. To do this, simply add implements 
java.io.FileFilter to the class definition. This works because the method signature for the accept () 
method in the javax.swing.+filechooser class matches the interface definition: public boolean 
accept(File file). 


Choosing Directories Instead of Files 


The JFileChooser supports three selection modes: files only, directories only, and files and 
directories. The fileSelectionMode property setting determines the mode of the chooser. The 
available settings are specified by the three JFileChooser constants: FILES ONLY, DIRECTORIES ONLY, 
and FILES _AND_DIRECTORIES. Initially, the file chooseris in JFileChooser.FILES ONLY mode. 
To change the mode, just call public void setFileSelectionMode(int newMode). 

In addition to the fileSelectionMode property, you can use the read-only 
fileSelectionEnabled and directorySelectionEnabled properties to determine the type 
of input currently supported by the file chooser. 


Adding Accessory Panels 


The JFileChooser supports the addition of an accessory component. This component can 
enhance the functionality of the chooser, including previewing an image or document, or 
playing an audio file. To respond to file selection changes, the accessory component should 
attach itself as a PropertyChangeListener to the JFileChooser. When the JFileChooser.w» 
SELECTED_FILE_CHANGED_PROPERTY property changes, the accessory then changes to reflect the 
file selection. Figure 9-28 shows how an image previewer accessory component might appear. 
Configuring the accessory for a chooser is just like setting any other property. 


fileChooser.setAccessory(new LabelAccessory(fileChooser)); 
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Figure 9-28. A JFileChooser with an accessory panel 


Listing 9-16 shows source for an Image component that displays an accessory icon. The 
selected image file becomes the icon for a JLabel component. The component does two scaling 
operations to make sure the dimensions of the image are sized to fit within the accessory. 


Listing 9-16. Custom Accessory for Use with JFileChooser 


import javax.swing.*; 
import java.beans.*; 
import java.awt.*; 
import java.io.*; 


public class LabelAccessory extends JLabel implements PropertyChangeListener ( 
private static final int PREFERRED WIDTH = 125; 
private static final int PREFERRED_HEIGHT = 100; 


public LabelAccessory(JFileChooser chooser) ( 
setVerticalAlignment(JLabel.CENTER); 
setHorizontalAlignment(JLabel.CENTER); 
chooser.addPropertyChangeListener(this); 
setPreferredSize(new Dimension(PREFERRED WIDTH, PREFERRED_HEIGHT)); 
J 
public void propertyChange(PropertyChangeEvent changeEvent) £ 
String changeName = changeEvent.getPropertyName(); 
if (changeName.equals(JFileChooser.SELECTED_FILE CHANGED PROPERTY)) € 
File file = (File)changeEvent.getNewValue(); 
if (file != null) £ 
Imagelcon icon = new Imagelcon(file.getPath()); 
if (icon.getIconWidth() > PREFERRED_WIDTH) ( 
icon = new Imagelcon(icon.getImage().getScaledInstance( 
PREFERRED_WIDTH, -1, Image.SCALE_DEFAULT)); 
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if (icon.getIconHeight() > PREFERRED_HEIGHT) 4 
icon = new Imagelcon(icon.getImage().getScaledInstance( 
-1, PREFERRED_HEIGHT, Image.SCALE_DEFAULT)); 
J 
J 
setIcon(icon); 
J 
J 
J 
hi 


Using the FileSystemView Class 


The FileSystemView class localizes access to platform-specific file system information. Where 
theJDK 1.1 version of java.io.File was fairly crippled in this respect, FileSystemViewn fills in to 
make it easier to design FileChooserUl objects. The Swing FileSystemView class provides three 
custom views as package-private subclasses of FileSystemView. They include support for UNIX 
and Windows, plus a generic handler. 

Although it isn't necessary to define your own FileSystemView, the class provides some 
features that can be useful outside the context of a JFileChooser. To get the view specific to the 
user's runtime environment, call public static FileSystemView getFileSystemView(). The 
class definition follows. 


public abstract class FileSystemView ( 
// Constructors 
public FileSystemView();  // Properties 
// Properties 
public File getDefaultDirectory(); 
public File getHomeDirectory(); 
public File[] getRoots(); 
// Class Methods 
public static FileSystemView getFileSystemView(); 
// Other Methods 
public File createFile0bject(File directory, String filename); 
public File createFileObject(String path); 
protected File createFileSystemRoot(File file); 
public abstract File createNewFolder(File containingDir) throws IOException; 
public File getChild(File parent, String filename); 
public File[] getFiles(File directory, boolean useFileHiding); 
public File getParentDirectory(File file); 
public String getsystemDisplayName(File file); 
public Icon getSystemIcon(File file); 
public String getSystemTypeDescription(File file); 
public boolean isComputerNode(File file); 
public boolean isDrive(File file); 
public boolean isFileSystem(File file); 
public boolean isFileSystemRoot(File file); 
public boolean isFloppyDrive(File file); 
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public boolean isHiddenFile(File file); 

public boolean isParent(File folder, File file); 
public boolean isRoot(File file); 

public Boolean isTraversable(File file); 


Note Notice that the isTraversable() method returns a Boolean, not a boolean. (I haven't a clue 
why the difference—perhaps somewhere an object is needed, and the primitive boolean wasn't sufficient.) 


FileView Class 


The final part ofthe JFileChooser class to examine is the FileView area where all the file names 
are listed. Each of the custom look and feel types has its own FileView area class. In addition, 
some of the predefined look and feel types, such as Motif, aren't changeable. Nevertheless, at 
least in the Metal and Windows file choosers, you can customize the icons for different file 
types or change the display name for a file. 

The five methods of the FileView class allowyou to change the name, icon, or description (two 
forms) of each File in the view. In addition, the FileView actually controls whether a directory 
is traversable, allowing you to program in a weak level ofaccess control. Nontraversable directories 
have a different default icon, because those directories cannot be browsed for file selection. 

Here's the definition of the abstract FileView class: 


public abstract class FileView ( 
public FileView(); 
public String getDescription(File file); 
public Icon getIcon(File file); 
public String getName(File file); 
public String getTypeDescription(File file); 
public Boolean isTraversable(File file); 


Note Like FileSystemView, the isTraversable() method returns a Boolean value, not a boolean one. 


Customizing the FileView requires creating a subclass and overriding the appropriate 
methods. By default, all the methods return null, indicating that you don't want to define 
custom behavior for a specific method. 

Once you've defined the file view, simply change the fileView property of your JFileChooser: 


fileChooser.setFileView(new JavaFileView()); 


Figure 9-29 shows the changed appearance of a Metal JFileChooser after installing a 
custom FileView. 
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Figure 9-29. Changing the FileView 


The JavaFileView class in Listing 9-17 provides a FileView implementation that customizes 
the appearance of files related to Java development—specifically, .java, .class, .jar, and 
«html or .htm files. (This is certainly not meant to be a comprehensive list of Java file types.) For 
each of these file types, a special icon instead of the default icon is displayed next to the name. 
In addition, for Java source files, the length of the file is displayed. (Imagine if every file attribute 
were being displayed!) Unfortunately, you can't modify the font or color from a FileView. 


Listing 9-17. Custom FileView for Some Java-Related File Types 


import java.io.File; 

import java.awt.*; 

import javax.swing.*; 

import javax.swing.tfilechooser.*; 


public class JavaFileView extends FileView ( 
Icon javalcon = new DiamondIcon(Color.BLUE); 
Icon classIcon = new DiamondIcon(Color.GREEN); 
Icon htmlIcon = new DiamondIcon(Color.RED); 
Icon jarlcon = new DiamondIcon(Color.PINK); 


public String getName(File file) ( 
String filename = file.getName(); 
if (filename.endsWith(".java")) ( 
String name = filename + " : " + file.length(); 
return name; 


J 


return null; 
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public String getTypeDescription(File file) ( 
String typeDescription = null; 
String filename = file.getName().toLowerCase(); 


if (filename.endsWith(".java")) £ 
typeDescription = "Java Source"; 
+ else if (filename.endsWith(".class"))( 
typeDescription = "Java Class File"; 
) else if (filename.endsWith(".jar"))( 
typeDescription = "Java Archive"; 
+ else if (filename.endsWith(".htm1") || filename.endsWith(".htm")) £ 
typeDescription = "Applet Loader”; 
J 
return typeDescription; 


J 


public Icon getIcon(File file) ( 
if (file.isDirectory()) ( 
return null; 
) 
Icon icon = null; 
String filename = file.getName().toLowerCase(); 
if (filename.endsWith(".java")) £ 
icon = javalcon; 
+ else if (filename.endsWith(".class"))( 
icon = classIcon; 
) else if (filename.endsWith(".jar")) 
icon = jarlcon; 
+ else if (filename.endsWith(".htm1") || filename.endsWith(".htm")) £ 
icon = htmllIcon; 
) 


return icon; 


Customizing a JFileChooser Look and Feel 


Each installable Swing look and feel provides a different JFileChooser appearance and set of 
default UTResource values. Figure 9-30 shows the appearance of the JFileChooser for the 
preinstalled set of look and feel types: Motif, Windows, and Ocean. 
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Figure 9-30. JFileChooser under different look and feel types 
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The available set ofUIResource-related properties for a JFileChooser is shown in Table 9-11. 
For the JFileChooser component, there are 83 different properties. Neatly all the properties 
relate to the button labels, mnemonics, icons, and tooltip text. 


Table 9-11. JFileChooser UlResource Elements 
Property String 


FileChooser 


FileChooser 


FileChooser 
FileChooser 
FileChooser 


FileChooser 


FileChooser. 


FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 


FileChooser. 


FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 


FileChooser. 


acceptAllFileFilterText 


.ancestorInputMap 


.cancelButtonMnemonic 


cancelButtonText 
cancelButtonToolTipText 
deleteFileButtonMnemonic 
deleteFileButtonText 
deleteFileButtonToolTipText 
detailsViewButtonAccessibleName 
detailsViewButtonToolTipText 


detailsViewIcon 


.directoryDescriptionText 
.directory0penButtonMnemonic 
.directory0penButtonText 
.directory0penButtonToolTipText 


enterFilenameLabelMnemonic 
enterFilenameLabelText 
fileDescriptionText 
fileNameLabelMnemonic 
fileNameLabelText 
filesLabelMnemonic 
filesLabelText 
filesOfTypeLabelMnemonic 
filesOfTypelLabelText 
filterlabelMnemonic 
filterlabelText 
foldersLabelMnemonic 


foldersLabelText 


helpButtonMnemonic 


Object Type 
String 
InputMap 
Integer 
String 
String 
Integer 
String 
String 
String 
String 
Icon 
String 
Integer 
String 
String 
String 
String 
String 
Integer 
String 
Integer 
String 
Integer 
String 
Integer 
String 
Integer 


String 


Integer 
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Table 9-11. JFileChooser UlResource Elements (Continued) 


Property String 


FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser 
FileChooser. 
FileChooser 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser. 
FileChooser 
FileChooser 
FileChooser 
FileChooser 


FileChooser. 


helpButtonText 
helpButtonToolTipText 
homeFolderAccessibleName 


homeFolderIcon 


.homeFolderToo1TipText 


listFont 


.listViewBackground 


listViewBorder 
listViewButtonAccessibleName 
listVienButtonToolTipText 
listViewIcon 
listVienWindowsStyle 
lookInLabelMnemonic 
lookInLabelText 
newFolderAccessibleName 
newFolderButtonMnemonic 
newFolderButtonText 
newFolderButtonToolTipText 
newFolderDialogText 
newFolderErrorSeparator 
newFolderErrorText 


newFolderIcon 


newFolderTool1TipText 
openButtonMnemonic 
openButtonText 
openButtonToo1TipText 
openDialogTitleText 


other.newFolder 


.other.newFolder.subsequent 
.win32.newFolder 
.win32.newFolder.subsequent 


.pathLabelMnemonic 


pathlLabelText 


Object Type 
String 
String 
String 
Icon 
String 
Font 
Color 
Border 
String 
String 
Icon 
Boolean 
Integer 
String 
String 
Integer 
String 
String 
String 
String 
String 
Icon 
String 
Integer 
String 
String 
String 
String 
String 
String 
String 
Integer 
String 
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Table 9-11. JFileChooser UlResource Elements (Continued) 


Property String Object Type 
FileChooser.read0Only Boolean 
FileChooser.renameFileButtonMnemonic Integer 
FileChooser.renameFileButtonText String 
FileChooser.renameFileButtonToolTipText String 
FileChooser.renameFileDialogText String 
FileChooser.renameFileErrorText String 
FileChooser.renameFileErrorTitle String 
FileChooser.saveButtonMnemonic Integer 
FileChooser.saveButtonText String 
FileChooser.saveButtonToolTipText String 
FileChooser.saveDialogTitleText String 
FileChooser.savelnLabelText String 
FileChooser.updateButtonMnemonic Integer 
FileChooser.updateButtonText String 
FileChooser.updateButtonToolTipText String 
FileChooser.upFolderAccessibleName String 
FileChooser.upFolderIcon Icon 
FileChooser.upFolderToo1TipText String 
FileChooser.usesSingleFilePane Boolean 
FileChooser.useSystemExtensionHiding Boolean 
FileChooserul String 


In addition to the more than 80 resources for JFileChooser, there are 5 additional ones as 
part of the FileView, which are shown in Table 9-12. 


Table 9-12. FileView UlResource Elements 


Property String Object Type 
FileView.computerIcon Icon 
FileView.directoryIcon Icon 
FileView.filelcon Icon 
FileView.floppyDrivelcon Icon 


FileView.hardDrivelcon Icon 
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Summary 


In this chapter, you explored the intricacies of Swing's pop-up and chooser classes. Instead of 
manually creating a JDialog and filling it with the necessary pieces, the Swing component set 
includes support for many different pop-up and chooser classes. Starting with the JOptionPane, 
you learned how to create informational, question, and input pop-ups. In addition, you 
explored how to monitor the progress of time-consuming tasks by using the ProgressMonitor 
and ProgressMonitorInputStream classes. 

After looking at the more general pop-up classes, you explored the specifics of Swing's 
color and file chooser classes: JColorChooser and JFileChooser. From each of these two classes, 
you can prompt the user for the requested input and customize the display in more ways than 
you can imagine. 

Now that you have a feel for the predefined pop-ups, itis time to move on to the 
LayoutManager classes in Chapter 10. With the help of the system layout managers, you can 
create even better user interfaces. 


CHAPTER 10 


Layout Managers 


l. Chapter 9, you learned about the various pop-up and chooser classes available from the 
Swing component set. In this chapter, you'll learn about the AWT and Swing layout managers. 

While this book focuses on the Swing component set, you can'tuse them in a vacuum. You 
need to understand both the AWT and Swing layout managers. In fact, you're more apt to use 
four of the five AWT layout managers than three of the five Swing layout managers. The AWT 
layout managers are FlowLayout, BorderLayout, GridLayout, CardLayout, and GridBagLayout. 
The Swing layouts are BoxLayout, OverlayLayout, ScrollPaneLayout, ViewportLayout, and 
SpringLayout. Another manager is JRootPane.RootLayout, which was described in Chapter 8. 

In addition to the layout managers, you'll look at several helper classes: GridBagLayout's 
constraint class GridBagConstraints, the SizeRequirements class used by both the BoxLayout 
and OverlayLayout managers, and the SpringLayout manager's associated Spring and 
SpringLayout.Constraints classes. 


Layout Manager Responsibilities 


Every container, such as a JPanel or Container, has a layout manager. That layout manager is 
responsible for positioning components, regardless of the platform or screen size. 

Layout managers eliminate the need to compute component placement on your own, 
which would be a losing proposition, since the size required for any component depends on 
the platform on which your program is deployed and the current look and feel. Even for a 
simple layout, the code required to discover component sizes and compute absolute positions 
could be hundreds of lines, particularly if you concern yourself with what happens when the 
user resizes a window. A layout manager takes care of this for you. It asks each component in 
the container how much space it requires, and then arranges the components on the screen as 
best it can, based on the component sizes on the platform in use, the available space, and the 
rules of the layout manager. 

To find out how much space a component needs, the layout manager calls the component's 
getMinimumSize(), getPreferredSize(), and getMaximumSize() methods. These methods report 
the minimum, preferred, and maximum space that a component requires to be displayed 
correctly. Thus, each component must know its space requirements. The layout manager then 
uses the component's space requirements to resize components and arrange them on the 
screen. Your Java program never needs to worry about platform-dependent positioning, beyond 
layout manager setup. 
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Note that a layout manager is free to ignore some ofits components; there is no requirement 
that a layout manager display everything. For example, a Container using a BorderLayout might 
include 30 or 40 components; however, the BorderLayout will display at most 5 ofthem (the last 
component placed in each ofits five named areas). Likewise, a CardLayout may manage many 
components but displays exactly one at a time. 

Besides ignoring components, a layout manager can do anything it wants with the compo- 
nents' minimum, preferred, and maximum size. It is free to ignore any or all of these. It makes 
sense that a layout manager can ignore a preferred size—after all, preferred means, “Give me 
this size ifit's available.” However, a layout manager can also ignore a minimum size. At times, 
there is no reasonable alternative because the container may not have enough room to display 
a component at its minimum size. How to handle this situation is left to the layout manager 
designer's discretion. 


LayoutManager Interface 


The LayoutManager interface defines the responsibilities of the manager that lays out the 
Component objects within a Container. As explained in the previous section, itis the duty of the 
layout manager to determine the position and size of each component within the Container. 
You will never call the methods ofthe LayoutManager interface directly; for the most part, layout 
managers do their work behind the scenes. Once you have created a LayoutManager object and 
told the container to use it (by calling setLayout (manager)), you're finished with it. The system 
calls the appropriate methods of the layout manager when necessary. Like any interface, 
LayoutManager specifies the methods a layout manager must implement but says nothing 
about how the LayoutManager does its job. 

The LayoutManager interface itselfis mostimportantifyou are writing a new layout manager. 
P'Il describe this interface first because it's the foundation on which all layout managers are 
based. P'll also describe the LayoutManager2 interface, which is used by some layout managers. 


Exploring the LayoutManager Interface 


Five methods make up the LayoutManager interface: 


public interface LayoutManager ( 
public void addLayoutComponent (String name, Component comp); 
public void layoutContainer(Container parent); 
public Dimension minimumLayoutSize(Container parent); 
public Dimension preferredLayoutSize(Container parent); 
public void removeLayoutComponent (Component comp); 
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If you create your own class that implements LayoutManager, you must define all five. 
As you will see, many of the methods do not need to do anything, but you must still include 
a stub with the appropriate signature. 

The addLayoutComponent () method is called only when you add components by calling the 
add(String, Component) or add(Component, Object) method, not just plain add (Component). 
For add(Component, Object), the Object must be of type String, or else that isn't called either. 


Exploring the LayoutManager2 Interface 


For layout managers that require each component to carry its layout manager constraints, the 
LayoutManager2 interface comes into play. The layout managers that use LayoutManager2 include 
BorderLayout, CardLayout, and GridBagLayout, to name a few. 

LayoutManager2 has five additional methods: 


public interface LayoutManager2 ( 
public void addLayoutComponent (Component comp, Object constraints); 
public float getLayoutAlignmentX(Container target); 
public float getLayoutAlignmentY(Container target); 
public void invalidatelayout(Container target); 
public Dimension maximumLayoutSize(Container target); 


The addLayoutComponent () method is called when you assign constraints to the component 
when adding it to the layout. In practice, this means that you added the component to the 
container by calling the add(Component component, Object constraints) or add(String name, 
Component component) methods, rather than the add(Component component) method. Itis up to 
the layout manager to decide what, if anything, to do with the constraints. For example, 
GridBagLayout uses constraints to associate a GridBagConstraints object to the component 
added, and BorderLayout uses constraints to associate a location (like BorderLayout . CENTER) 
with the component. 


FlowLayout Class 


FlowLayout is the default layout manager for a JPanel. A FlowLayout adds components to the 

container in rows, working in the order defined by the getComponentOrientation() method of 
Component, typically left to right in the United States and western Europe. When it can't fit more 
components in a row, it starts a new row, similar to a word processor with word wrap enabled. 
When the container is resized, the components within it are repositioned based on the container's 
new size. Components within a FlowLayout-managed container are given their preferred size. 
Tf there is insufficient space, you do not see all the components, as illustrated in Figure 10-1. 
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Figure 10-1. The default FlowLayout setup, with seven buttons and three different screen sizes. 
As the third example shows, if the screen is too small, the components will not be shrunk to fit all 
the components. 


There are three constructors for creating the FlowLayout layout manager: 


public FlowLayout() 
public FlowLayout(int alignment) 
public FlowLayout(int alignment, int hgap, int vgap) 


If an alignment is not specified, components within a FlowLayout-managed container are 
centered. Otherwise, the setting is controlled by one of the following constants: 

e CENTER 

e LEADING 

e LEFT 

e RIGHT 

e TRAILING 


For the typical left-to-right orientation, LEADING and LEFT are the same, as are TRAILING and 
RIGHT. For a language like Hebrew, these would be reversed. Figure 10-2 shows the effect of 
several different alignments. 
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Figure 10-2. FlowLayout with three different alignments 


You can specify the gaps, in pixels, for the spacing between components, both horizontal 
(hgap) and vertical (vgap). Gaps default to five pixels unless specified. Itis possible to specify 


negative gaps if you want components to be placed on top of one another. 


BorderLayout Class 


BorderLayout is the default layout manager for the content pane of a JFrame, JHindow, JDialog, 
JInternalFrame, and JApplet. It provides for a more flexible way of positioning components 


along the edges ofthe window. Figure 10-3 shows a typical BorderLayout. 


[> vortertayosr A 


North 


Figure 10-3. Sample BorderLayout 
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When using BorderLayout, you add components with constraints to identify in which of 
the five locations to place the component. Ifyou don't specify a constraint, the component is 
added to the center area. Adding multiple components to the same area shows only the last 
component, although technically speaking, the other components are still within the container; 
they are just not shown. 

There are two constructors for creating the BorderLayout layout manager: 


public BorderLayout() 
public BorderLayout(int hgap, int vgap) 


Unlike FlowLayout, the default gaps for a BorderLayout are zero pixels, meaning the 
components are positioned right next to one another. 

The constraints to use when adding a component to a BorderLayout-managed container 
are constants of the BorderLayout class: 


+ AFTER_LAST_ LINE 

+ AFTER_LINE_ENDS 

+ BEFORE FIRST LINE 
+ BEFORE LINE BEGINS 
+ CENTER 

+ EAST 

+ LINE END 

+ LINE START 

+ NORTH 

+ PAGE END 

+ PAGE START 

+ SOUTH 

+ WEST 


With only five regions to add a component to, you would expect only five constants. As with 
FlowLayout, the additional constants deal with proper positioning when the component 
orientation is reversed, either horizontally or vertically. For the typical left-to-right, top-to- 
bottom orientation, the common set of values is as follows: 


e AFTER_LAST_LINE, PAGE_END, SOUTH 

e AFTER_LINE_ENDS, LINE_END, EAST 

e BEFORE_FIRST_LINE, PAGE_START, NORTH 
e BEFORE_LINE_ BEGINS, LINE_START, WEST 


+ CENTER 
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Tip Using the BEFORE and AFTER constants, as opposed to the NORTH, SOUTH, EAST, and WEST 
constants, is recommended, though all are supported. 


You do not need specify all five areas ofthe container. The component in the north region 
takes up the entire width of the container along its top. South does the same along the bottom. 
The heights of north and south will be the preferred heights of the component added. The east 
and west areas are given the widths of the component each contains, where the heightis whatever 
is left in the container after satisfying north's and south's height requirements. Any remaining 
space is given to the component in the center region. 

The way to place multiple components into one ofthe regions of a BorderLayout-managed 
container is to add them to a different container first, and then add them to the BorderLayout- 
managed container. For instance, if you want a label and text field in the north area of 
a BorderLayout-managed container, place them in the west and center areas of another 
BorderLayout-managed container first, as shown here: 


JPanel outerPanel = new JPanel(new BorderLayout()); 
JPanel topPanel = new JPanel(new BorderLayout()); 

JLabel label = new JLabel("Name: ">; 

JTextField text = new JTextField(); 

topPanel.add(label, BorderLayout.BEFORE_ LINE BEGINS); 
topPanel.add(text, BorderLayout.CENTER); 
outerPanel.add(topPanel, BorderLayout.BEFORE_FIRST_LINE); 


GridLayout Class 


The GridLayout manager is ideal for laying out objects in rows and columns, where each cell in 
the layout has the same size. Components are added to the layout from left to right, top to 
bottom. A call to setLayout(new GridLayout(3, 4)) changes the layout manager of the current 
container to a GridLayout with three rows and four columns, as shown in Figure 10-4. 


September December 


Figure 10-4. Sample GridLayout 
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There are three constructors for creating the GridLayout layout manager: 


public GridLayout() 
public GridLayout(int rows, int columns) 
public GridLayout(int rows, int columns, int hgap, int vgap) 


Typically, you would explicitly specify the overall grid size for your GridLayout-managed 
container. However, you can set the number of rows or columns to be zero, and the layout will 
grow without bounds in the direction with a zero setting. 


Caution !f both rows and columns are specified to be zero to the Grid Layout constructor, a runtime 
exception of 111egalArgumentException will be thrown. 


The actual number of rows and columns drawn is based on the number of components 
within the container. The GridLayout tries to observe the number of rows requested first. 
If the requested number of rows is nonzero, the number of columns is determined by 
(+of components + rows -— 1) /rows. If your request is for zero rows, the number of rows to use is 
determined by a similar formula: (+ofcomponents + columns -— 1)/columns. Table 10-1 demon- 
strates this calculation. The last entry in the table is of special interest: if you request a 3x3 grid 
but place only four components in the layout, you actually get a 2x2 layout as a result. Ifyou do 
not want to be surprised, size the GridLayout based on the actual number of objects you plan 
to add to the display. 


Table 10-1. GridLayout Row/Column Calculation 


Rows Columns + Components Display Rows Display Columns 
0 1 10 10 1 
0 2 10 5 2 
1 0 10 1 10 
2 0 10 2 5 
2 3 10 2 5 
2 3 20 2 10 
3 2 10 3 4 
3 3 3 3 1 
3 3 4 2 2 


GridBagLayout Class 


GridBagLayout is the most complex and most flexible ofthe layout managers. Although it sounds 
like it should be a subclass of GridLayout, it's a different beast altogether. With GridLayout, 
elements are arranged in arectangular grid, and each element in the containers sized identically 
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(where possible). With GridBagLayout, elements can have different sizes and can occupy 
multiple rows or columns. 
There is only the no-argument constructor for GridBagLayout: 


public GridBagLayout() 


The position and behavior of each element is specified by an instance of the 
GridBagConstraints class. By properly constraining the elements, you can specify the number 
ofrows and columns a component occupies, which component grows when additional screen 
real estate is available, and various other restrictions. The actual grid size is based on the 
number of components within the GridBagLayout and the GridBagConstraints ofthose objects. 
For example, Figure 10-5 shows a GridBagLayout with seven components, arranged in a 3x3 grid. 


lolxi 


Figure 10-5. GridBagLayout with seven components in a 3x3 grid 


Note The maximum capacity of a screen using GridBagLayout is 512 rows by 512 columns. This is 
specified by the protected MAXGRIDSIZE constant of the layout manager. 


The code used to create Figure 10-5 is shown in Listing 10-1. 


Listing 10-1. Seven-Button GridBagLayout 


import java.awt.*; 
import java.awt.event.*; 
import javax.swing.*; 
import java.text.*; 


public class GridBagButtons ( 
private static final Insets insets = new Insets(0,0,0,0); 
public static void main(final String args[]) ( 
Runnable runner = new Runnable() £ 
public void run() £ 

final JFrame frame = new JFrame("GridBagLayout"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
frame.setLayout(new GridBagLayout()); 
JButton button; 
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// Row One - Three Buttons 

button = new JButton("One"); 

addComponent (frame, button, 0, 0, 1, 1, 
GridBagConstraints.CENTER, GridBagConstraints.BOTH); 

button = new JButton("Two"); 

addComponent (frame, button, 1, 0, 1, 1, 
GridBagConstraints.CENTER, GridBagConstraints.BOTH); 

button = new JButton("Three"); 

addComponent (frame, button, 2, 0, 1, 1, 
GridBagConstraints.CENTER, GridBagConstraints.BOTH); 

// Row Two - Two Buttons 

button = new JButton("Four"); 

addComponent (frame, button, 0, 1, 2, 1, 
GridBagConstraints.CENTER, GridBagConstraints.BOTH); 

button = new JButton("Five"); 

addComponent (frame, button, 2, 1, 1, 2, 
GridBagConstraints.CENTER, GridBagConstraints.BOTH); 

// Row Three - Two Buttons 

button = new JButton("Six"); 

addComponent (frame, button, 0, 2, 1, 1, 
GridBagConstraints.CENTER, GridBagConstraints.BOTH); 

button = new JButton("Seven"); 

addComponent (frame, button, 1, 2, 1, 1, 
GridBagConstraints.CENTER, GridBagConstraints.BOTH); 

frame.setSize(500, 200); 

frame.setVisible(true); 

4 
E 
EventQueue.invokeLater(runner); 


J 


private static void addComponent(Container container, Component component, 
int gridx, int gridy, int gridwidth, int gridheight, int anchor, 
int fil) ( 
GridBagConstraints gbc = new GridBagConstraints(gridx, gridy, 
gridwidth, gridheight, 1.0, 1.0, anchor, fill, insets, 0, 0); 
container.add(component, gbc); 
J 
y 


Most of the work in Listing 10-1 is done by the helper method addComponent (), which 
creates a set of constraints for the component to be added to the container. 
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GridBagLayout Rows and Columns 


To help you visualize the grid of components in the GridBagLayout, Figure 10-6 indicates how 
the layout manager counts cells. The top-left cell in the layout has location (0, 0). There's nothing 
surprising about buttons one, two, three, six, and seven. Each of those occupies a 1x1 area of 
the layout's 3x3 grid. Button four occupies a 2x1 area; itis placed at location (0, 1), and thus 
occupies this cell plus the cell at (1, 1). Likewise, button five occupies a 1x2 area and takes up 
the cells at (2, 1) and (2, 2). The total size of the layout is determined entirely by the components 
that are placed in it and their constraints. 


Couumns 


1 


Figure 10-6. How GridBagLayout counts rows and columns 


GridBagConstraints Class 


The magic of the layout manager is strictly controlled by the different GridBagConstraints 
objects passed in for each component added to the container. Each specifies how to display a 
specific component. Unlike most other layout managers, which have a built-in idea about 
what to do with their display, the GridBagLayout is a blank slate. The constraints attached to the 
components tell the layout manager how to build its display. 

Every component added to a GridBagLayout container should have a GridBagConstraints 
object associated with it. When an object is first added to the layout, it is given a default set 
of constraints (see Table 10-2). Calling container.add(Component, GridBagConstraints) or 
gridBagLayout.setConstraints(GridBagConstraints) applies the new set of constraints to the 
component. 

GridBagConstraints has two constructors: 


public GridBagConstraints() 

public GridBagConstraints(int gridx, int gridy, int gridwidth, int gridheight, 
double weightx, double weighty, int anchor, int fill, Insets insets, int ipadx, 
int ipady) 
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Using the no-argument constructor for GridBagConstraints starts with all the defaults in 
Table 10-2. You can leave the individual settings alone and just set the individual fields. All are 
public, without getter methods. While you can just blindly pass in all the constraints to the 
GridBagConstraints constructor, itis better to describe the different fields separately. 


Table 10-2. GridBagConstraints Defaults 


Variable Value Description 


anchor CENTER If the component is smaller than the space available, it will be 
centered within its region. 


fill NONE The component should not resize itself if extra space is avail- 
able within its region. 


gridx RELATIVE The component associated with this constraint will be 
positioned relative to the last item added. If all components 
have gridx and gridy RELATIVE, they will be placed ina 


single row. 
gridy RELATIVE The component associated with this constraint will be 
positioned relative to the last item added. 
gridwidth 1 The component will occupy a single cell wide within the layout. 
gridheight 1 The component will occupy a single cell high within the layout. 
insets Ox0x0x0 No extra space is added around the edges of the component. 
ipadx 0 There is no internal horizontal padding for the component. 
ipady 0 There is no internal vertical padding for the component. 
weightx 0 The component will not get any extra horizontal space, 
if available. 
weighty 0 The component will not get any extra vertical space, if 
available. 
Component Anchoring 


The anchor variable specifies the direction in which the component will drift in the event itis 
smaller than the space available for it. CENTER is the default. The absolute values are NORTH, SOUTH, 
EAST, WEST, NORTHEAST, NORTHWEST, SOUTHEAST, and SOUTHWEST. The relative values are PAGE_START, 
PAGE END, LINE START, LINE_END, FIRST_LINE_START, FIRST LINE END, LAST LINE START, and 
LAST_LINE END. 


Component Resizing 


The value of fi11 controls the component's resize policy. Iffi11 is NONE (the default), the layout 
manager tries to give the component its preferred size. If fi11 is VERTICAL, it resizes in height if 
additional space is available. If $111 is HORIZONTAL, it resizes in width. If f111 is BOTH, the layout 
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manager takes advantage of all available space in both directions. Figure 10-7 demonstrates 
VERTICAL, HORIZONTAL, and NONE values (generated by changing the GridBagConstraints.BOTH 
settings in Listing 10-1). 


£- GridBagLayout 


Horizontal 
lol 
One | Two Three 


None 


Figure 10-7. GridBagLayout with different fill values 


Grid Positioning 


The gridx and gridy variables specify the grid position where this component would be placed. 
(0, 0) specifies the cell at the origin of the screen. The gridwidth and gridheight variables 
specify the number ofrows (gridwidth) and columns (gridheight) a particular component 
occupies. Table 10-3 shows the gridx, gridy, gridwidth, and gridheight values for the example 
shown earlier in Figure 10-5. 
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Table 10-3. The gridx, gridy, gridwidth, and gridheight Values for Figure 10-5 


Component gridx gridy gridwidth gridheight 
One 0 0 1 1 
Two 1 0 1 1 

Three 2 0 1 1 
Four 0 1 2 1 
Five 2 1 0 2 

Six 0 2 1 1 
Seven 1 2 1 3 


Itisn't necessary to set gridx and gridy to a specific location. Ifyou set these fields to 
RELATIVE (the default), the system calculates the location for you. According to the Javadoc 
comments, if gridx is RELATIVE, the component appears to the right of the last component 
added to the layout. If gridy is RELATIVE, the component appears below the last component 
added to the layout. However, this is misleadingly simple. RELATIVE placement works best if 
you are adding components along a row or column. In this case, there are four possibilities for 
placement: 


+ With gridx and gridy RELATIVE, components are placed in one row. 


+ With gridx RELATIVE and gridy constant, components are placed in one row, each to the 
right of the previous component. 


+ With gridx constant and gridy RELATIVE, components are placed in one column, each 
below the previous component. 


+ Varying gridx or gridy while setting the other field RELATIVE appears to start a new row, 
placing the component as the first element of the new row. 


If gridwidth or gridheight is set to REMAINDER, the component will be the last element of 
the row or column occupying any space that's remaining. For the components in the rightmost 
column of Table 10-3, for example, the gridwidth values could have been REMAINDER. Similarly, 
gridheight could be set to REMAINDER for the components in the bottom row. 

gridwidth and gridheight may also have the value RELATIVE, which forces the component 
to be the next-to-last component in the row or column. Looking back to Figure 10-5, if button 
six had a gridwidth of RELATIVE, button seven wouldn't appear because button five is the last 
item in the row, and six is already next to last. If button five had a gridheight of RELATIVE, the 
layout manager would reserve space below it so the button could be the next-to-last item in 
the column. 


Padding 


The insets value specifies the external padding in pixels around the component (the space 
between the component and the edge of the cell or cells allotted to it). An Insets object can 
specify different padding for the top, bottom, left, or right side ofthe component. 


CHAPTER 10 LAYOUT MANAGERS 


ipadx and ipady specify the internal padding within the component. ipadx specifies the extra 
space to the right and left of the component (so the minimum width increases by 2xipadx pixels). 
ipady specifies the extra space above and below the component (so the minimum height increases 
by 2xipady pixels). The difference between insets (external padding) and ipadx/ipady (internal 
padding) can be confusing. The insets don't add space to the component itself; they are 
external to the component. ipadx and ipady change the component's minimum size, so they 
do add space to the component itself. 


Weight 


weightx and weighty describe how to distribute any additional space within the container. 
They allow you to control how components grow (or shrink) when the user resizes the 
container, or the container is just bigger to start. 

Hfweightx is 0.0, the component won't get any additional space available in its row. Ifone 
or more components in a row have a positive weightx, any extra space is distributed propor- 
tionally between them. For example, if one component has a weightx value of 1.0 and the 
others are all 0.0, the one component will get all the additional space. Iffour components in a 
row each has a weightx value of 1.0, and the other components have weightx values of 0.0, the 
four components each get one quarter of the additional space. weighty behaves similarly to 
weightx, but in the other direction. Because weightx and weighty control the distribution of 
extra space in any row or column, setting either for one component may affect the position of 
the other components. 


CardLayout Class 


The CardLayout layout manager is significantly different from the other layout managers. 
Whereas the other layout managers attempt to display all the components within the container 
atonce, a CardLayout displays only one component at a time. That component can be a component 
or container, where the latter lets you see multiple components laid out based on the layout 
manager of the embedded container. 

Now that the JTabbedPane component (described in the next chapter) is available, CardLayout 
is rarely used. 


BoxLayout Class 


Swing's BoxLayout manager allows you to position components in either a horizontal row ora 
vertical column within your own container. In addition to using BoxLayout within your own 
container, the Box class (described in the next chapter) offers a container that uses BoxLayout as 
its default layout manager. 

The benefit of using BoxLayout over something like FlowLayout or GridLayout is that BoxLayout 
works to honor each component's x and y alignment properties as well as its maximum size. 
And BoxLayout is much easier to use than GridBagLayout. Figure 10-8 demonstrates BoxLayout 
in action. Previously, you would have needed to figure out the necessary layout constraints to 
get GridBagLayout to behave like this. 
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£- Box Example E 101 x] 
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Figure 10-8. BoxLayout example, before and after resizing 


Creating a BoxLayout 


BoxLayout has a single constructor: 
public BoxLayout(Container target, int axis) 


The constructor takes two arguments. The first argument is the container with which this 
instance of the layout managers to be associated, and the second is the layout direction. Valid 
directions are BoxLayout .X_AXIS for a left-to-right layout and BoxLayout .Y_AXIS for a top-to- 
bottom layout. 


Caution Trying to set the axis to something other than the equivalent value of the two constructor 
constants will throw an AWTError. If the layout manager is associated with a container that isn't the 
container passed in to the constructor, an AWTError will be thrown when the layout manager tries to lay 
out the other (that is, wrong) container. 


Once you create a BoxLayout instance, you can associate the layout manager with a 
container as you would with any other layout manager. 


JPanel panel = new JPanel(); 
LayoutManager layout = new BoxLayout (panel, BoxLayout.X_AXIS); 
panel.setLayout (layout); 


Unlike all the other system-provided layout managers, a BoxLayout and container are bound 
together in two directions, from manager to container as well as from container to manager. 


Tip The Box class, described in Chapter 11, lets you create a container and set ¡ts layout manager to 
BoxLayout all in one step. 
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Laying Out Components 


Once you've set the layout manager of a container to BoxLayout, that's really all you do directly 
with the layout manager. Adding components to the container is done with either the 
add(Component component) or add(Component component, int index) method. Although 
BoxLayout implements the LayoutManager?2 interface, implying the use of constraints, it currently 
uses none. Therefore, itisn't necessary to use add (Component component, Object constraints). 

When it comes time to lay out the container, BoxLayout does its work. The BoxLayout manager 
tries to satisfy the minimum and maximum sizes of the components within the container, as 
well as their x-axis and y-axis alignments. Alignment values range from 0.0f to 1.0f. (Alignment 
settings are floating-point constants, not doubles, hence the need for the f) 

By default, all Component subclasses have an x-axis alignment of Component. CENTER_ALTGNMENT 
and a y-axis alignment of Component. CENTER_ALTGNMENT. However, all AbstractButton subclasses 
and JLabel have a default x-axis alignment of Component .LEFT_ALIGNMENT. Table 10-4 shows 
the constants available from Component for these component properties, settable with either 
setAlignmentX(float newValue) or setAlignmentY(float newValue). The different alignments 
work identically, except in different directions. In the case of horizontal alignments, this is 
similar to left-, center-, or right-justifying a paragraph. 


Table 10-4. Component Alignments 


Setting Value 
Vertical Alignment 

Component . TOP_ALTGNMENT 0.0f 
Component. CENTER_ALIGNMENT 0.5f 
Component .BOTTOM_ALIGNMENT 1.0f 
Horizontal Alignment 

Component .LEFT_ALIGNMENT 0.0f 
Component . CENTER_ALIGNMENT 0.5f 
Component .RIGHT_ALIGNMENT 1.0f 


Laying Out Components with the Same Alignments 


The BoxLayout manager acts differently depending on the alignment ofthe components within 
the container being managed. If all the alignments are the same, those components whose 
maximum size is smaller than the container will be aligned based on the alignment setting. For 
instance, if you have a wide area with a vertical BoxLayout and small buttons within it, the 
horizontal alignment will serve to left-, center-, or right-justify the buttons. Figure 10-9 shows 
how this looks. 
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Left Center Right 


Figure 10-9. Three y-axis BoxLayout containers, each with components having the same 
horizontal alignments 


The key point demonstrated here is that if all the components share the same alignment 
setting, the actual alignment of all the components within the managed container is the 
components' alignment setting. 

The source used to generate Figure 10-9 is shown in Listing 10-2. 


Listing 10-2. Y-Axis Alignment 


import javax.swing.*; 
import java.awt.*; 
import java.awt.event.*; 


public class YAxisAlignX ( 
private static Container makelt(String title, float alignment) ( 
String labels[] = ("--", "oo", Uoo===--- My Uornonooooo-- ee 


JPanel container = new JPanel(); 
container.setBorder(BorderFactory.createTitledBorder(title)); 
BoxLayout layout = new BoxLayout(container, BoxLayout.Y_AXIS); 
container.setLayout(layout); 


for (int i=0,n=labels.length; i<n; i++) ( 
JButton button = new JButton(labels[i]); 
button.setAlignmentX(alignment); 
container.add(button); 


J 


return container; 


y 


public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("Alignment Example"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


Container panel1 = makelt("Left", Component.LEFT_ALTIGNMENT); 
Container panel2 = makeIt("Center", Component.CENTER_ALIGNMENT); 
Container panel3 = makelt("Right", Component.RIGHT_ALIGNMENT); 
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frame.setLayout(new FlowLayout()); 
frame.add(panel1); 
frame.add(panel2); 
frame.add(panel3); 


frame.pack(); 
frame.setVisible(true); 
hi 
5 
EventQueue.invokeLater(runner); 
y 
) 


An x-axis BoxLayout works similarly when all the components have the same vertical align- 
ments. Instead of being left-, center-, and right-justified, the components would appear at the 
top, center, and bottom of the container. Figure 10-10 demonstrates this appearance. 
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Figure 10-10. Three x-axis BoxLayout containers that each have components with the same 
vertical alignments 


The source for the example shown in Figure 10-10 requires just a few changes from 
Listing 10-2. The complete source is provided in Listing 10-3. 


Listing 10-3. X-Axis Alignment 


import javax.swing.*; 
import java.awt.*; 
import java.awt.event.*; 


public class XAxisAlignY ( 
private static Container makelt(String title, float alignment) ( 
String labels[] = qe”, L-", to; 


JPanel container = new JPanel/(); 
container.setBorder(BorderFactory.createTitledBorder(title)); 
BoxLayout layout = new BoxLayout(container, BoxLayout.X_AXIS); 
container.setLayout (layout); 
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for (int i=0,n=labels.length; i<n; i++) ( 
JButton button = new JButton(labels[i]); 
button.setAlignmentY (alignment); 
container.add(button); 

) 

return container; 


J 


public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("Alignment Example"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


Container panel1 = makelt("Top", Component. TOP_ALIGNMENT); 
Container panel2 = makeIt("Center", Component.CENTER_ALIGNMENT); 
Container panel3 = makeIt("Bottom", Component .BOTTOM_ALIGNMENT); 


frame.setLayout(new GridLayout(1, 3)); 
frame.add(panel1); 
frame.add(panel2); 
frame.add(panel3); 


frame.setSize(423, 171); 
frame.setVisible(true); 
) 
5 
Event0Queue.invokeLater(runner); 


J 


Laying Out Components with Different Alignments 


Working with small components that have the same alignment is relatively simple. However, 
if the components in a container managed by a BoxLayout have different alignments, things 
become more complex. In addition, the components won't necessarily be displayed the way 
you might expect. For a vertical box, the components appear as follows: 


+ Ifa component has its x alignment set to Component. LEFT_ALIGNMENT, the left edge of the 
component will be aligned with the center of the container. 


+ Ifa component has its x alignment set to Component .RIGHT_ALIGNMENT, the right edge of 
the component will be aligned with the center ofthe container. 


+ Ifa component has its x alignment set to Component. CENTER_ALTGNMENT, the component 
will be centered within the container. 


+ Other alignment values cause components to be placed in varying positions (depending 
on the value) relative to the center of the container. 
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To help you visualize this mixed alignment behavior, Figure 10-11 shows two BoxLayout 
containers. The left container has two components, one with a left alignment (the button 
labeled 0.0) and another with a right alignment (the button labeled 1.0). Here, you can see that 
the left edge of the right componentis aligned to the right edge of the left component, with the 
common edge being the centerline ofthe container. The right container shows additional 
components placed between the 0.0 and 1.0 alignment settings. The label ofeach button repre- 
sents its alignment setting. 


olx] 


Mixed | Mixed | 
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Figure 10-11. Two y-axis BoxLayout containers with mixed horizontal alignments 


For a horizontal box, the y alignment works the same relative to the top and bottom ofthe 
components on an x-axis, as illustrated in Figure 10-12. 
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Figure 10-12. Two x-axis BoxLayout containers with mixed vertical alignments 


Laying Out Larger Components 


In the examples so far, the size of the components is always smaller than the space available. 
Those examples demonstrate a subtle difference between Swing and the original AWT compo- 
nents. The default maximum size of Swing components is the preferred size ofthe component. 
With AWT components, the default maximum size is a dimension with a width and height of 
Short .MAX_VALUE. Ifthe previous examples had used AWT Button components instead of Swing 
JButton components, you would see surprisingly different results. You would also see different 
results ifyou manually set the maximum size property of the components to some value wider 
or higher than the screen for the appropriate BoxLayout. Using AWT Button components makes 
things a little easier to demonstrate. 

Figure 10-9 showed three y-axis BoxLayout containers in which the components inside the 
container share the same horizontal alignment setting and the maximum size of each button is 
constrained. Ifthe component's maximum size is unconstrained, or just larger than the container, 
you see something like Figure 10-13, in which the y-axis BoxLayout container has four Button 
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components with the same horizontal alignment. Notice that instead of aligning to the left, 
center, or right, the components grow to fill all available space. 


£ Alignment Example 101 x/ 


AWT Button 


Figure 10-13. Y-axis BoxLayout containers with the same vertical alignments and 
unconstrained size 


Ifthe components had different alignments and an unconstrained maximum size, you 
would get yet another behavior. Any component with an alignment not at the minimum (0.0f) or 
maximum (1.0f) setting will grow to fill the entire space. If components with both the minimum 
and maximum alignment settings are present, the middle edges of those two components will 
align in the middle, as Figure 10-14 demonstrates. 
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Figure 10-14. Y-axis BoxLayout containers with different vertical alignments, unconstrained size, 
and both minimum/maximum alignment present 


Tf, however, only one component has an edge case (0.0 or 1.0) and is in a container with 
components having other alignments, that edge-case component will growtoward somewhere 
other than the middle of the container. This behavior is shown in Figure 10-15. The x-axis 
BoxLayout containers work similarly with different horizontal alignments. 
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Figure 10-15. Y-axis BoxLayout containers with different vertical alignments, unconstrained size, 
and only one alignment at minimum/maximum 


OverlayLayout Class 


As its name implies, the OverlayLayout class is for layout management of components that lie 
on top of one another. When using add(Component component), the order in which you add 
components to a container with an OverlayLayout manager determines the component layering. If 
you use add (Component component, int index) instead, you can add components in any order. 
Although OverlayLayout implements the LayoutManager2 interface, like BoxLayout it currently 
doesn't use any constraints. 

Determining the two-dimensional position ofthe components requires the layout manager 
to examine the x and y alignment properties of the contained components. Each component 
will be positioned such that its x and y alignment properties define a point shared by all the 
components, called the axis point of the layout manager. If you multiply the alignment value 
by the component's size in each appropriate direction, you'll get each part ofthe axis point for 
that component. 

After the axis point is determined for each component, the OverlayLayout manager calcu- 
lates the position of this shared point within the container. To calculate this position, the layout 
manager averages the different alignment properties ofthe components, and then multiplies 
each setting by the width or height ofthe container. This position is where the layout manager 
places the axis point, and the components are then positioned over this shared point. 

For example, suppose you have three buttons: a 25x25 white button on top ofa 50x50 gray 
button on top of a 100x100 black button. Ifthe x and y alignment of each button is 0.0f, the 
shared axis point for the three components is their upper-left corner, and the components are 
all in the upper-left corner of the container. Figure 10-16 shows how this might appear. 

If the x and y alignment of each button is 1.0f, the axis point for the three components is 
their bottom-right corner, and the components are in the bottom-right corner ofthe container. 
Figure 10-17 shows this appearance. 
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Figure 10-16. Sample OverlayLayout with 0.0 x and y alignments 
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Figure 10-17. Sample OverlayLayout with 1.0 x and y alignments 


If the x and y alignment of each button is 0.5f, the axis point for the three components is 


their center, and the components are in the center of the container. Figure 10-18 shows this 
appearance. 


retar A 


Change Alignment 


Minimum Maximum Central Mixed 


Figure 10-18. Sample OverlayLayout with 0.5 x and y alignments 
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Having all components with the same alignment is relatively easy to visualize, but what 
would happen ifthe components had different alignments? For instance, ifthe small button 
had x and y alignments of 0.0f, the medium button had alignments of 0.5f, and the large button 
had alignments of 1.0f, where would everything appear? Well, the first thing the layout manager 
calculates is the axis point. Based on the specific alignment of each button, the axis point would 
be the upper-left corner of the small button, the middle ofthe medium button, and the bottom- 
right corner of the large button. The position of the axis point within the container would then 
be the average of the alignment values multiplied by the dimensions of the container. The 
average of 0, 0.5, and 1 for both directions places the axis point at the center of the container. 
The components are then placed and layered from this position, as Figure 10-19 shows. 


£ Overlay Example 3 


Axis Point 


Change Alignment 


Minimum Maximum Central Mixed 


Figure 10-19. Three buttons managed by an OverlayLayout with 0.0, 0.5, and 1.0 xand y 
alignments 


When you set up overlaid components, make sure that the optimizedDrawingEnabled 
property ofthe container ofthe components is setto false. This ensures proper repainting and 
event propagation. 

To try out the OverlayLayout manager, use the source that follows in Listing 10-4. It 
provides selectable buttons to demonstrate interactively the effect of varying the alignment 
values. Initially, the program has everything centered. 


Listing 10-4. OverLayout Example 


import javax.swing.*; 
import java.awt.*; 
import java.awt.event.*; 


public class OverlaySample ( 
public static final String SET_MINIMUM = "Minimum"; 
public static final String SET_MAXIMUM = "Maximum" ; 
public static final String SET_CENTRAL = "Central"; 
public static final String SET_MIXED "Mixed"; 
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static JButton smallButton = new JButton(); 


static JButton mediumButton = new JButton(); 


static JButton largeButton = new JButton(); 


public static void setupButtons(String command) ( 


J 


1f (SET MINIMUM. equals(command)) £ 


J 
J 


smallButton.setAl 


smallButton.setAl 


Lign 
ign 


entX(0.of); 
entY(0.of); 


mediumButton.setAlignmentX(0.0f); 
mediumButton.setAlignmentY(0.0f); 


largeButton.setAl 


largeButton.setA] 


ign 
Lign 


else if (SET_MAXIMUM, 


smallButton.setAl 
smallButton.setAl 


ign 
ign 


entX(0.of); 
entY(0.of); 
equals(command)) £ 
entX(1.0f); 
entY(1.0f); 


mediumButton.setAlignmentX(1.0f); 
mediumButton.setAlignmentY(1.0f); 


largeButton.setAl 


largeButton.setA] 


ign 
Lign 


else if (SET_CENTRAL. 


smallButton.setAl 


smallButton.setAl 


ign 
Lign 


entX(1.0f); 
entY(1.0f); 
equals(command)) € 
entX(0.5f); 
entY(0.5f); 


mediumButton.setAlignmentX(0.5f); 
mediumButton.setAlignmentY(0.5f); 


largeButton.setAl 
largeButton.setAl 


ign 
ign 


entX(0.5f); 
entY(0.5f); 


else if (SET_MIXED.equals(command)) ( 


smallButton.setAl 


smallButton.setAl 


Lign 
ign 


entX(0.of); 
entY(0.of); 


mediumButton.setAlignmentX(0.5f); 
mediumButton.setAlignmentY(0.5f); 


largeButton.setAl 
largeButton.setAl 


else ( 


ign 
ign 


throw new Illegal 


// Redraw panel 


((Panel)largeButton.getParent()).revalidate(); 


lArgumentException("Illegal Command: 


entX(1.0f); 
entY(1.0f); 


public static void main(String args[]) ( 


" 


+ command); 
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final ActionlListener generalActionlistener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
JComponent comp = (JComponent)actionEvent.getSource(); 
System.out.println ( 
actionEvent.getActionCommand() + 


”,o.n 


+ comp.getBounds ()); 


) 
E 


final ActionListener sizingActionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
setupButtons(actionEvent.getActionCommana()); 
Ñ 
5 


Runnable runner = new Runnable() £ 
public void run() £ 
JFrame frame = new JFrame("Overlay Example”); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


JPanel panel = new JPanel() £ 
public boolean isOptimizedDrawingEnabled() ( 
return false; 
) 
y; 
LayoutManager overlay = new OverlayLayout (panel); 
panel.setLayout(overlay); 


Object settings[][] = ( 
("Smal1", new Dimension(25, 25), Color.white), 
["Medium", new Dimension(50, 50), Color.gray), 
("Large", new Dimension(100, 100), Color.blackj 
y; 
JButton buttons[] = £smallButton, mediumButton, largeButtony; 


for (int i=0, n=settings.length; i<n; i++) [ 
JButton button = buttons[i]; 
button.addActionListener(generalActionListener); 
button.setActionCommand((String)settings[i][0]); 
button.setMaximumSize((Dimension)settings[i][1]); 
button.setBackground((Color)settings[i][2]); 
panel .add(button); 
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setupButtons(SET_ CENTRAL); 


JPanel actionPanel = new JPanel(); 
actionPanel.setBorder(BorderFactory.createTitledBorder("Change Alignment")); 
String actionSettings[] = (SET MINIMUM, SET MAXIMUM, SET CENTRAL, 
SET_MIXED); 
for (int i=0, n=actionSettings.length; i<n; i++) ( 
JButton button = new JButton(actionSettings[i]); 
button.addActionListener(sizingActionListener); 
actionPanel.add(button); 


J 


frame.add(panel, BorderLayout.CENTER); 
frame.add(actionPanel, BorderLayout.SOUTH); 


frame.setSize(400, 300); 
frame.setVisible(true); 
) 
E 
EventQueue.invokeLater(runner); 
J 
) 


SizeRequirements Class 


The BoxLayout and OverlayLayout managers rely on the SizeRequirements class to determine 
the exact positions of the contained components. The SizeRequirements class contains various 
static methods to assist in the calculations necessary to position components in either an 
aligned or a tiled manner. The layout managers use this class to calculate their components' x 
coordinates and width and y coordinates and height. Each pair is calculated separately. Ifthe 
associated layout manager needs both sets of attributes for positioning, the layout manager 
asks the SizeRequirements class separately for each. 


ScrollPaneLayout Class 


The JScrol1Pane class, a container class that will be described in Chapter 11, uses the 
ScrollPaneLayout manager. Trying to use the layout manager outside a JScrol1Pane isn't 
possible because the layout manager checks to see ifthe container object associated with 
the layout manager is an instance of JScrollPane. See Chapter 11 for a complete description 
of this layout manager (and its associated ScrollPaneConstants interface) in the context of 
the JscrollPane. 
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ViewportLayout Class 


The ViewportLayout manager is used by the JViewport class, a container class (to be described 
in Chapter 11). The JVienport is also used within the Scrol1PaneLayout/JScrollPane combination. 
Like Scrol1PaneLayout, the VienportLayout manager is closely tied to its component, JViewport 
in this case, and isn't usable outside the component, except in a subclass. In addition, the 
JViewport class is rarely used outside a JScrol1Pane. The VienportLayout manager will be discussed 
in the context of its container, JViewport, in Chapter 11. 


SpringLayout Class 


The newest addition to the Java layout manager frontis the SpringLayout manager, added with 
the J2SE 1.4 release. This allows you to attach “springs” to components so that they are laid out 
relative to other components. For instance, with SpringLayout, you can say that a button 
appears attached to the right border, no matter what size a user makes the screen. 

The SpringLayout manager relies on SpringlLayout.Constraints for the component 
constraints. This works similarly to the GridBagConstraints class that complements the 
GridBagLayout manager. Each component added to the container can have an attached 
SpringLayout.Constraints. Therein lies the end to the similarities between these two types 
of constraints. 

You usually don't need to add the component with the constraints. Instead, you can add 
the component, and then typically attach the constraints separately. There is nothing stopping 
you from adding the constraints with the component, but SpringLayout.Constraints is nota 
simple class. Itis a collection of Spring objects, each a different constraint on the component. 
You need to add each Spring constraint separately to SpringLayout.Constraints. You do this 
by setting specific constraints on an edge of the component. Using the four SpringLayout 
constants of EAST, WEST, NORTH, and SOUTH, you call the setContraints(String edge, Spring 
spring) method of SpringLayout.Constraints, where the String is one of the constants. 

For instance, if you want to add a component in the top left of a container, you can set up 
two springs of a constant size, combine them together, and add the component to the 
container with the combined set, as shown here: 


Component left = ...; 

Springlayout layout = new SpringLayout(); 

JPanel panel = new JPanel (layout); 

Spring xPad = Spring.constant(5); 

Spring yPad = Spring.constant(25); 

Springlayout.Constraints constraint = new SpringLayout.Constraints(); 
constraint.setConstraint(SpringLayout.WEST, xPad); 
constraint.setConstraint(Springlayout.NORTH, yPad); 

frame.add(left, constraint); 
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That doesn't looktoo complicated, but it gets more difficultwhen you need to add the next 
component, either to the right of the first or belowit. You can't just say to add the component 
n pixels over. You must actually add the padding to the edge of the earlier component. To find 
the edge of the earlier component, you ask the layout manager with getConstraint(), passing 
in the edge you want and the component, asin layout .getConstraint(SpringlLayout.EAST, left), 
to get the location of the right edge of the first component. From that location, you can add in 
the necessary padding and attach it to the edge of the other component, as shown here: 


Component right = ...; 

Spring rightsideOfLeft = layout.getConstraint(Springlayout.EAST, left); 
Spring pad = Spring.constant(20); 

Spring leftEdgeOfRight = Spring.sum(rightSideOfLeft, pad); 

constraint = new SpringlLayout.Constraints(); 
constraint.setConstraint(SpringlLayout.WEST, leftEdgeOfRight); 
constraint.setConstraint(SpringLayout.NORTH, yPad); 

frame.add(right, constraint); 


This works perfectly well, but it gets tedious as the number of components increases. To 
eliminate the in-between steps, you can add the components without the constraints, and 
then add each separately, connecting the components via the putConstraint() method of 
SpringLayout. 


public void putConstraint(String el, Component c1, int pad, String e2, 
Component c2) 

public void putConstraint(String el, Component c1, Spring s, String e2, 
Component c2) 


Here, instead of asking for the edge and adding in the padding yourself, the putConstraint () 
call combines the tasks for you. To demonstrate, the following snippet adds the same component 
constraints to the right component as the previous one, but using putConstraint() instead of 
using SpringLayout.Constraints directly: 


Component left = ...; 

Component right = ...; 

SpringlLayout layout = new SpringLayout(); 

JPanel panel = new JPanel (layout); 

panel.add(left); 

panel.add(right); 

layout .putConstraint(SpringlLayout.WEST, left, 5, Springlayout.WEST, panel); 
layout .putConstraint(SpringLayout.NORTH, left, 25, SpringLayout.NORTH, panal); 
layout .putConstraint(SpringlLayout.NORTH, right, 25, SpringLayout.NORTH, panel); 
layout .putConstraint(Springlayout.WEST, right, 20, Springlayout.EAST, left); 


To help you visualize the use of SpringLayout, Sun has a tool available from https: // 
bean-builder.dev.java.net/ called The Bean Builder. The tool is primarily intended to be used 
when working with JavaBean components, but it works well to see SpringLayout in action. 
Figure 10-20 shows what the tool looks like on startup through Java WebStart. 
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The Bean Builder - Design Mode [tutorial.xml] 
File View Help 


ara 


Containers [| Menu 


Es | e | [E [fl le [E O Cr] e E E e 


Event Management e Instantiate Bean | | Design Mode 


Swing 


[ok] 


Property Inspector - javax.swing.JFrame 


53 javax.swing.JFrame 
q WEE javax. swing. JRootPane L 
HO javax.swing.JPanel Sy TextField a 
q WA javax.swing.JLayeredPane a a 
? O javax.swing.JPanel 
9 El javax.swing.JScrollPane 
q MER javax.swing.JViewport 
9 El javax.swing.JList 
IN javax.swing.CellRendererPane 
9 ma javax.swing.JScrollPane$ScrollBar 
[al javax.swing.plaf.metal.MetalScrollButton 
ll javax.swing.plaf.metal.MetalScrollButton 


22 [Standard y 


Value 


Remove All 


alwaysOnTop [J false 

238,238,238 lus] 

laos  Jv:[259  |width: [315 — Height: [326 
componentOrientation java.awtComponentOrientation 

cursor java. awtCursor[Default Cursor] 


defaultCloseOperation HIDE_ON_CLOSE 5 A 


[Y] true 
(1) 
focusCycleRoot [y] true 
focusTraversalKeysEna... | [Y] true 
focusTraversalPolicy javax.swinq.LayoutFocusTraversalPolicy 
focusTraversalPolicyPro...| [] false 
focusable [v] true 
focusableWindowsState [v] true 


[piaiog ]y][rz IJAAA 
Dialog, Plain, 12 


0,0,0 MA o 


Properties for: javax.swing.JFrame 


Figure 10-20. The Bean Builder startup 


Around the edges of each component lies a set of four boxes, one each for north, south, 
east, and west. You can drag an arrow out of a box and connectit to any other box. Had the tool 
been a little more sophisticated, it would permit you to specify gap sizes for springs, too, but, 
asitis, the screen will look something like Figure 10-21 during screen design. Each arrow created is 
mapped to a specific call to the putConstraint() method. 
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Figure 10-21. Bean Builder and SpringLayout 


Listing 10-5 offers source similar to what would be used to generate a screen like Figure 10-21. 
Notice that you must use the content pane of the JFrame directly, as putConstraint() wants 
that container, not the frame itself. 


Listing 10-5. SpringLayout Example 


import java.awt.*; 
import javax.swing.*; 


public class SpringSample ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() £ 
JFrame frame = new JFrame("SpringLayout"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
Container contentPane = frame.getContentPane(); 


SpringlLayout layout = new SpringLayout(); 
contentPane.setLayout (layout); 


Component left = new JLabel("Left"); 
Component right = new JTextField(15); 


contentPane.add(left); 
contentPane.add(right); 
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layout .putConstraint(SpringLayout.WEST, left, 10, SpringLayout.WEST, 
contentPane); 

layout .putConstraint(SpringlLayout.NORTH, left, 25, SpringLayout.NORTH, 
contentPane); 

layout .putConstraint(SpringlLayout.NORTH, right, 25, SpringLayout.NORTH, 
contentPane); 

layout .putConstraint(SpringlLayout.WEST, right, 20, Springlayout.EAST, left); 


frame.setSize(300, 100); 
frame.setVisible(true); 
) 
E 
EventQueue.invokeLater(runner); 
) 
) 


Summary 


This chapter introduced AWT's predefined layout managers FlowLayout, BorderLayout, 
GridLayout, GridBagLayout, and CardLayout, as well as Swing's predefined layout managers 
BoxLayout, OverlayLayout, ScrollPaneLayout, ViewportLayout, and SpringLayout. You saw how 
the various alignment settings affect the components within a container whenever you use a 
layout manager such as BoxLayout or OverlayLayout. In addition, you were introduced to the 
SizeRequirements class, which is used internally by BoxLayout and OverlayLayout. 

In Chapter 11, you'll look atthe JScrollPane and JViewport containers, which use the 
ScrollPaneLayout and ViewportLayout managers, plus several other sophisticated Swing 
container classes. 
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Advanced Swing Containers 


Chao: 10 explored the layout managers available within AWT and Swing. In this chapter, 
you'll look at some ofthe containers that rely on these layout managers, as well as some others 
that work without a layout manager. 

Starting with the Box class, you'll discover the best way to use the BoxLayout manager to 
create a single row or column of components. Next, you'll learn about the JSplitPane container, 
which is a bit like a specialized Box with just two components inside. The JSplitPane provides 
a splitter bar that acts as a divider users can drag to resize the components to suit their needs. 

Then you'll explore the JTabbedPane container, which works something like a container 
whose layout manager is a CardLayout, except with tabs builtinto the container that allow you 
to move from card to card. You'll be able to create multiple-screen, property-sheet dialog 
boxes for user input with JTabbedPane. 

The last two advanced Swing containers covered are the JScrollPane and JViewport. Both 
ofthese components offer the ability to display a section of a large component within a limited 
amount of screen real estate. The JScrollPane adds scrollbars to a display area so that you can 
move around a large component that sits within a small area. In fact, the JScrol1Pane uses the 
JViewport to “clip away” the part of the larger component that shouldn't be seen. 

So, let's get started and look at the first container, the Box class. 


Box Class 


As asubclass of JComponent, the Box class is a special Java Container for creating a single row or 
column of components with the help of the BoxLayout manager. The Box container works like a 
JPanel (or Panel), but has a different default layout manager, BoxLayout. Using BoxLayout can 
be a little cumbersome without a Box, which simplifies working with BoxLayout. You can associate 
the BoxLayout manager with a container in just three steps: manually creating the container, 
creating the layout manager, and associating the manager with the container. When you create 
an instance of Box, you perform these three steps at once. In addition, you can use an inner 
class of Box called Box. Filler to better position components within the container. 
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Creating a Box 
You have three ways to create a Box, offered by one constructor and two static factory methods: 
public Box(int direction) 


Box horizontalBox = new Box(BoxLayout.X_AXIS); 
Box verticalBox  = new Box(BoxLayout.Y_ AXIS); 


public static Box createHorizontalBox() 
Box horizontalBox = Box.createHorizontalBox(); 


public static Box createVerticalBox() 
Box verticalBox  = Box.createVerticalBox(); 


Note The Box class is not designed to be used as a JavaBean component. Use of this container within an 
IDE can be awkward. 


The less frequently used constructor requires a direction for the main axis of the layout 
manager. The direction is specified by either of two BoxLayout constants, X_AXIS or Y_AXIS, to 
create a horizontal or vertical box, respectively. Instead of manually specifying the direction, 
simply create a Box with the desired orientation by using one ofthe provided factory methods: 
createHorizontalBox() or createVerticalBox(). 

Filling a horizontal and vertical Box with a JLabel, a JTextField, and a JButton demonstrates 
the flexibility of BoxLayout, as shown in Figure 11-1. 


Top 


Left/Middle Right Middle 


Figure 11-1. A horizontal and a vertical box 


For the horizontal container, the label and button are at their preferred widths because 
their maximum size is the same as their preferred size. The text field uses up the remaining 
space. 

In the vertical container, the label and button sizes are their preferred size, too, because 
their maximum size is still the same as their preferred size. The text field's height fills the height 
that the label and button don't use, and its width is as wide as the container. 

The source code for creating the screens shown in Figure 11-1 follows in Listing 11-1. 
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Listing 11-1. Working with the Box 


import javax.swing.*; 
import java.awt.*; 


public class BoxSample ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() £ 
public void run() £ 
JFrame verticalFrame = new JFrame("Vertical"); 
verticalFrame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
Box verticalBox = Box.createVerticalBox(); 
verticalBox.add(new JLabel("Top")); 
verticalBox.add(new JTextField("Middle")); 
verticalBox.add(new JButton("Bottom")); 
verticalFrame.add(verticalBox, BorderLayout.CENTER); 
verticalFrame.setSize(150, 150); 
verticalFrame.setVisible(true); 


JFrame horizontalFrame = new JFrame("Horizontal"); 
horizontalFrame.setDefaultCloseO0peration(JFrame.EXIT_ON_ CLOSE); 
Box horizontalBox = Box.createHorizontalBox(); 
horizontalBox.add(new JLabel("Left")); 
horizontalBox.add(new JTextField("Middle")); 
horizontalBox.add(new JButton("Right")); 
horizontalFrame.add(horizontalBox, BorderLayout.CENTER); 
horizontalFrame.setSize(150, 150); 
horizontalFrame.setVisible(true); 

5 

EventQueue.invokelLater(runner); 

) 
) 


Box Properties 


As Table 11-1 shows, there are only two Box properties. Although the layout property inherits a 
setLayout (LayoutManager) method from its parent Container class, if called on a Box object, the 
class throws an AWTError. Once the BoxLayout manager is set duringits construction, it can't be 
changed, nor can its direction. 


Table 11-1. Box Properties 
Property Name Data Type Access 


accessibleContext AccessibleContext Read-only 


layout LayoutManager Write-only 
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Working with Box. Filler 


The Box class has an inner class Box. Filler to help you create invisible components for better 
component positioning within a container whose layout manager is BoxLayout. By directly 
manipulating the minimum, maximum, and preferred size ofthe created component, you can 
create components that grow to fill unused space or remain a fixed size, making screens more 
aesthetically pleasing to your users. 


Note Technically speaking, the use of Box. Fi1ler is not limited to containers whose layout manager is 
BoxLayout. You can use them anywhere you can use any other Component. The components are just invisible. 


Instead of directly using the Box. Filler class, several static methods of the Box class can 
help you create the appropriate filler components. The factory methods allow you to categorize 
these components by type, instead of by minimum, maximum, or preferred size. You”! look at 
these methods in the next two sections. 

If you're interested in the class definition, it's shown next. Like the Box class, Box. Filler 
isn't meant to be used as a JavaBean component. 


public class Box.Filler extends Component implements Accessible ( 
// Constructors 
public Filler(Dimension minSize, Dimension prefSize, Dimension maxSize); 
// Properties 
public AccessibleContext getAccessibleContext(); 
public Dimension getMaximumSize(); 
public Dimension getMinimumSize(); 
public Dimension getPreferredSize(); 
// Others 
protected AccessibleContext accessibleContext; 
public void changeShape(Dimension minSize, Dimension prefSize, Dimension maxSize); 


Creating Areas That Grow 


If a component has a dimensionless minimum and preferred size, and a maximum size bigger 
than the screen, the component will grow to take up unused space between components in the 
container along one or both axes. In the case of a Box, or more precisely, a container whose 
layout manager is BoxLayout, the growth occurs along the layout manager's initially chosen 
direction (either BoxLayout .X_AXIS or BoxLayout .Y_AXIS). For a horizontal box, the growth affects 
the component's width. For a vertical box, the growth is reflected in the component's height. 

The name commonly given to this type of growing component is glue. The two flavors of 
glue are direction-independent glue and direction-dependent glue. The following factory 
methods of Box are used to create the glue components: 
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public static Component createGlue() 
// Direction independent 

Component glue = Box.createGlue(); 
aBox.add(glue); 


public static Component createHorizontalGlue(); 

// Direction dependent: horizontal 

Component horizontalGlue = Box.createHorizontalGlue(); 
aBox.add(horizontalGlue); 


public static Component createVerticalGlue() 

// Direction dependent: vertical 

Component verticalGlue = Box.createVerticalGlue(); 
aBox.add(verticalGlue); 


Once you create glue, you add it to a container in the same way as any other component, 
by using Container .add(Component) or one of the other add() varieties. Glue allows you to align 
components within a container, as Figure 11-2 shows. 


-101x) 


Beginning Glue 


Left Middle Right 


2 Middle Glues 


Left | Middle | Right 


Beginning/End Glues 


Left | Middle | Right 


End Glue 


Left | Middle | Right 


Figure 11-2. Using glue in a Box 


You can add glue components to any container whose layout manager honors minimum, 
maximum, and preferred size properties of a component, such as BoxLayout. For instance, 
Figure 11-3 demonstrates what happens when you add a glue component to a JMenuBar just 
before adding the last JMenu. Because the layout manager for a JMenuBar is BoxLayout (actually 
the subclass javax.swing.plaf.basic.DefaultMenuLayout), this action pushes the last menu to 
the right edge of the menu bar, similar to the Motif/CDE style of help menus. 


Caution | recommend that you avoid using the glue capability described here to set up help menus on 
menu bars. Eventually, the public void setHelpMenu(JMenu menu) of JMenuBar will be implemented 
and won't throw an Error. Of course, many of us are still waiting for this to happen. 
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olx 
File Edit Help 


Figure 11-3. Using glue in a JMenuBar 


Creating Rigid Areas 


Because a glue component grows to fill the available space, if you want to have a fixed distance 
between components, you need to create a rigid component, or strut. When doing so, you 
specify the strut's size. Struts can be two-dimensional, requiring you to specify the width and 
height of the component; or, they can be one-dimensional, requiring you to specify either the 
width or height. 


public static Component createRigidArea(Dimension dimension) 

// Two-dimensional 

Component rigidArea = Box. createRigidArea(new Dimension(10, 10)); 
aBox.add(rigidArea); 


public static Component createHorizontalStrut(int width) 
// One-dimensional: horizontal 

Component horizontalStrut = Box. createHorizontalStrut(10); 
aBox.add(horizontalStrut); 


public static Component createVerticalStrut(int height) 
// One-dimensional: vertical 

Component verticalStrut  = Box. createVerticalStrut(10); 
aBox.add(verticalStrut); 


Caution Although direction-independent glue created with createGlue() shows no side effects if 
you change container direction, creating a rigid area may cause layout problems if the axis is later changed. 
(Imagine dragging a menu bar and dropping it along the right side from the top.) That's because the compo- 
nent has a dimensionless minimum size. Using createRigidArea() isn't recommended, unless you truly 
want a two-dimensional empty component. 
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Figure 11-4 demonstrates several struts in action. Notice that you can have varying strut 
distances between different components, and struts atthe end of a container may have no 
effect. After a user resizes a screen, the strut distance between components remains fixed, as 
you can see in Figure 11-4. 


í Horizontal Strut. - 101 xf 


Beginning Strut 


Left Middle | Right 


2 Middle Struts 
| Left Jl Middle ] Right 
Beginning/End Struts 

(ter | made [rio 


End Strut 


Left | Middle | Right | 


Before Resizing 


=10/x] 
Beginning Strut 

[Left | Middle [| Right | 

2 Middle Struts 

Left Middle Right 
Beginning/End Struts 

[Left | Middle [ Right | 
End Strut 


Left | Middle [ Right 


After Resizing 


Figure 11-4. Using struts in a Box 


JSplitPane Class 


Similar to the Box container, the JSplitPane container allows you to display components in a 
single row or column. Whereas a Box can contain any number of components, a JSplitPane is 
meant to display two—and only two—components. The components are of variable size and 
separated by a movable divider. The divideris specially constructed in that the end user can grab 
itand drag the divider to adjust the size ofthe contained components. Figure 11-5 demonstrates 
both vertical and horizontal split panes, shown before and after moving the divider. 
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left button 


right button 


Vertical 


Divider 


left button | right button 


Horizontal 


left button right button 


After Moving 


Figure 11-5. Examples of JSplitPane containers 


Creating a JSplitPane 


There are five constructors for JSplitPane. With them, you can initialize the orientation ofthe 
contained component pair, setthe continuousLayout property, or initialize the pair of components 
for the container. 


public JSplitPane() 
JSplitPane splitPane = new JSplitPane(); 


public JSplitPane(int newOrientation) 
JSplitPane splitPane = new JSplitPane(JSplitPane.VERTICAL SPLIT); 


public JSplitPane(int newO0rientation, boolean newContinuousLayout) 
JSplitPane splitPane = new JSplitPane(JSplitPane.VERTICAL SPLIT, true); 


public JSplitPane(int newOrientation, Component newLeftComponent, 
Component nemRightComponent) 

JComponent topComponent = new JButton("Top Button"); 

JComponent bottomComponent = new JButton("Bottom Button"); 

JSplitPane splitPane = new JSplitPane(JSplitPane.VERTICAL_ SPLIT, 
topComponent, bottomComponent); 
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public JSplitPane(int newOrientation, boolean newContinuousLayout, 
Component newLeftComponent, Component newRightComponent) 

JSplitPane splitPane = new JSplitPane(JSplitPane.VERTICAL SPLIT, true, 
topComponent, bottomComponent); 


Unless otherwise specified, the orientation is horizontal. Orientation can be specified by 
either ofthe JSplitPane constants VERTICAL SPLIT or HORIZONTAL_SPLIT. The continuousLayout 
property setting determines how the split pane reacts when the user drags the divider. When 
the setting is false (the default), only the divider is redrawn when dragged. When the setting is 
true, the JSplitPane resizes and redraws the components on each side of the divider as the 
user drags the divider. 


Note If the orientation is JSplitPane.VERTICAL_SPLIT, you can think of the top component as the left 
component and the bottom component as the right component. 


If you're using the no-argument constructor, the initial set of components within the split 
pane is made up of buttons (two JButton components). Two other constructors explicitly set 
the initial two components. Surprisingly, the remaining two constructors provide no components 
within the container by default. To add or change the components within the JSplitPane, see 
the “Changing JSplitPane Components” section that's coming up shortly. 


JSplitPane Properties 
Table 11-2 shows the 17 properties of JSplitPane. 


Table 11-2. JSplitPane Properties 


Property Name Data Type Access 
accessibleContext AccessibleContext Read-only 
bottomComponent Component Read-write 
continuousLayout boolean Read-write bound 
dividerlocation double Write-only 
dividerlLocation int Read-write bound 
dividerSize int Read-write bound 
lastDividerLocation int Read-write bound 
leftComponent Component Read-write 
maximumDividerLocation int Read-only 


minimumDividerLocation int Read-only 
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Table 11-2. JSplitPane Properties (Continued) 


Property Name Data Type Access 
oneTouchExpandable boolean Read-write bound 
orientation int Read-write bound 
resizeWeight double Read-write bound 
rightComponent Component Read-write 
topComponent Component Read-write 
validateRoot boolean Read-only 

UI SplitPaneUI Read-write bound 
UlClassID String Read-only 
Setting Orientation 


Besides initializing the orientation within the constructor, you can change the JSplitPane 
orientation by changing the orientation property setting to either JSplitPane.VERTICAL_SPLIT 
or JSplitPane.HORIZONTAL_SPLIT. Ifyou try to change the property to a nonequivalent setting, 
an IllegalArgumentException is thrown. 

Dynamically changing the orientation at runtime is not recommended because it can 
confuse a user. However, if you're using a visual development tool, you can explicitly set the 
orientation for this property after creating the JSplitPane. When not programming visually, 
you would normally initialize the orientation when you create the JSplitPane. 


Changing JSplitPane Components 


There are four read-write properties for the different positions of a component within a 
JSplitPane: bottomComponent, leftComponent, rightComponent, and topComponent. In reality, 
these four properties represent two components internally: The left and top components are 
one; the right and bottom components represent the other. 

You should use the properties that are appropriate for the orientation of your JSplitPane. 
Using the inappropriate property methods can make life difficult for the maintenance 
programmer. Imagine, after creating a user interface, seeing something like the following code 
six months later: 


JComponent leftButton = new JButton("Left"); 

JComponent rightButton = new JButton("Right"); 

JSplitPane splitPane = new JSplitPane(JSplitPane.VERTICAL SPLIT); 
splitPane.setLeftComponent(leftButton); 
splitPane.setRightComponent(rightButton); 


If you glance at the source, you might think that the screen will contain a button to the left 
and one to the right based on the variable names and the setXXXComponent () methods used. 
But because the instantiated JSplitPane has a vertical orientation, the interface that's created 
looks like Figure 11-6. The variable names are used because of the button labels, not their position. 
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Figure 11-6. Adding left/right buttons to a vertical JSplitPane 


The code is more understandable if the setTopComponent () and setBottomComponent () 
methods are used with better variable names: 


JComponent topButton = new JButton("Left"); 

JComponent bottomButton = new JButton("Right"); 

JSplitPane splitPane = new JSplitPane(JSplitPane.VERTICAL SPLIT); 
splitPane.setTopComponent (topButton); 
splitPane.setBottomComponent (bottomButton); 


Moving the JSplitPane Divider 


Initially, the divider is shown below or to the right of the preferred size of the top or left 
component. At any time, you can reset the divider position to that position by calling the 
resetToPreferredSizes() method of JSplitPane. If you want to programmatically position the 
divider, you can change the dividerLocation property with setDividerLocation(newLocation). 
This property can be changed to an int position, representing an absolute distance from the 
top or left side, or it can be set to a double value between 0.0 and 1.0, representing a percentage 
ofthe JSplitPane container width. 


Caution Changing the property setting to a double value outside the range of 0.0 and 1.0 results in an 
I1legalArgumentException being thrown. 


If you want to set the divider location, you must wait for the component to be realized. 
Essentially, that means it must be visible. While there are roundabout ways of doing this, the 
most direct way is to attach a HierarchyListener to the JSplitPane and watch for when the 
HierarchyEvent is of type SHOWING_CHANGED. This is demonstrated in the following code fragment, 
changing the divider location to 75%. 


HierarchyListener hierarchyListener = new HierarchyListener() ( 
public void hierarchyChanged(HierarchyEvent e) ( 
long flags = e.getChangeFlags(); 
if ((flags 4 HierarchyEvent.SHOWING_CHANGED) == 
HierarchyEvent. SHOWING CHANGED) 4 
splitPane.setDividerLocation(.75); 
J 
J 
A 


splitPane.addHierarchyListener(hierarchyListener); 
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Although you can set the dividerLocation property with a double value, you can get only 
an int, indicating its absolute position. 


Tip With the system-provided look and feel classes, pressing the F8 key allows you to move the divider 
with the keyboard keys such as Home, End, or the arrows. F8 isn'ta modifier like Shift or Alt. Instead, pressing 
F8 moves the focus to the divider so that it can be moved with keystrokes. 


Resizing Components and Working with a One-Touch Expandable Divider 


Limitations exist on the resizing of components within the JSplitPane. The JSplitPane honors 
the minimum size of each contained component. If grabbing and moving the divider line will 
cause a component to shrink to less than its minimum size, the scroll pane won't let the user 
drag the divider past that minimum size. 


Note You can always programmatically position the divider to be anywhere, even if it makes a component 
smaller than its minimum size. However, this isn't a good idea because the component has a minimum size 
for a good reason. 


Ifthe minimum dimensions of a component are too large for a JSplitPane, you need to 
change the component's minimum size so that the divider can use some of that component's 
space. For AWT components, changing the minimum size of a standard component requires 
subclassing. With Swing components, you can simply call the setMinimumsize() method of 
JComponent with a new Dimension. Nevertheless, minimum sizes are set for a reason. The compo- 
nent probably won't look right if you explicitly shrink its minimum size. 

A better approach is available for allowing one component to take up more space than 
another: Set the oneTouchExpandable property of the JSplitPane to true. When this property is 
true, an icon is added to the divider, allowing a user to completely collapse one of the two 
components to give the other component the entire area. In the example in Figure 11-7, the 
icon is a combination up-and-down arrow. 

Figure 11-7 shows how this icon might appear (as rendered by the Ocean look and feel) 
and illustrates what happens after selecting the up arrow on the divider to expand the lower 
component to its fullest size. Clicking again on the icon on the divider returns the components 
to their previous positions. Clicking on the divider somewhere other than on the icon will position 
the divider in such a way that the collapsed component is at its preferred size. 


CHAPTER 11 ADVANCED SWING CONTAINERS 


One-Touch 
Expandable Icon 


Default 


£ Expandabl- Split 


Expanded 


Figure 11-7. Setting and using the oneTouchExpandable property 


Note There's no easy way to alter the one-touch expandable icon or change how the divider is rendered. 
Both are defined by the BasicSplitPaneDivider subclass and created in the createDefaultDivider() 
method of the BasicSplitPaneUl subclass for the specific look and feel. One thing you can easily change 
is the border around the divider, which is a custom border. 


The lastDividerLocation property allows you or the system to inquire about the previous 
divider location. The JSplitPane uses this property when the user selects the maximizer icon to 
undo the minimization of one ofthe components in the JSplitPane. 


Caution Beware of components that base their minimum size on the container size or their initial size! 
Placing them in a JSplitPane may require you to manually set the minimum and/or preferred size of the 
components. The components that most frequently cause problems when used within a JSplitPane are 
JTextArea and JScrollPane. 


Resizing the JSplitPane 


If additional space is available within the JSplitPane that is not required by the preferred size 
of the components it contains, this space is allocated based on the resizeWeight property 
setting. The initial setting of this property is 0.0, meaning the right or bottom component gets 
any additional space. Changing the setting to 1.0 would give all the space to the left or top 
component. A value of 0.5 would split the space evenly between the two components. Figure 11-8 
shows the effect of these changes. 


389 


390 


CHAPTER 11 ADVANCED SWING CONTAINERS 


l0/x 


-l0/x 


Default Resize Weight (0.0) 


Top 


Bottom 


Resize Weight 1.0 


lol 


Top 


Bottom 


Resize Weight 0.5 


Figure 11-8. Changing the resize weight 


Listening for JSplitPane Property Changes 


The JSplitPane class defines the following constants to help with listening for bound property 
changes: 


CONTINUOUS LAYOUT PROPERTY 
DIVIDER_LOCATION PROPERTY 
DIVIDER_SIZE PROPERTY 
LAST_DIVIDER_LOCATION PROPERTY 
ONE_TOUCH_EXPANDABLE_ PROPERTY 
ORIENTATION PROPERTY 


RESIZE WEIGHT_PROPERTY 


One way of listening for when the user moves the divider is to watch for changes to the 
lastDividerLocation property. The example in Listing 11-2 attaches a PropertyChangeListener 
to a JSplitPane displaying the current divider location, the current last location, and the previous 
last location. The component above and below the divider is the OvalPanel class (discussed in 
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Chapter 4), drawn to fill the dimensions ofthe component. This component helps to demon- 
strate the effect of having the continuousLayout property set to true. 


Listing 11-2. Listening for JSplitPane Property Changes 


import javax.swing.*; 
import java.awt.*; 
import java.beans.*; 


public class PropertySplit ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() £ 
public void run() £ 
JFrame frame = new JFrame("Property Split"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


// Create/configure split pane 

JSplitPane splitPane = new JSplitPane(ISplitPane.VERTICAL SPLIT); 
splitPane.setContinuousLayout (true); 
splitPane.setOneTouchExpandable(true); 


// Create top component 
JComponent topComponent = new OvalPanel(); 
splitPane.setTopComponent (topComponent) ; 


// Create bottom component 
JComponent bottomComponent = new OvalPanel(); 
splitPane.setBottomComponent (bottomComponent); 


// Create PropertyChangeListener 
PropertyChangeListener propertyChangeListener = 
new PropertyChangeListener() ( 
public void propertyChange (PropertyChangeEvent changeEvent) ( 
JSplitPane sourceSplitPane = (JSplitPane)changeEvent.getSource(); 
String propertyName = changeEvent.getPropertyName(); 
if (propertyName.equals( 
JSplitPane.LAST DIVIDER LOCATION PROPERTY)) £ 
int current = sourceSplitPane.getDividerlLocation(); 
System.out.println ("Current: " + current); 
Integer last = (Integer)changeEvent.getNewValue(); 
System.out.println ("Last: " + last); 
Integer priorlast = (Integer)changeEvent.getOldValue(); 
System.out.println ("Prior last: " + priorLast); 


$; 
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5 


// Attach listener 
splitPane.addPropertyChangelistener(propertyChangelistener); 


frame.add(splitPane, BorderLayout.CENTER); 
frame.setSize(300, 150); 
frame.setVisible(true); 


J 


EventQueue.invokeLater(runner); 


J 
J 


As the following sample output demonstrates, when you run the previous program, you'll 
notice that the lastDividerLocation property changes to reflect the divider's being dragged. 
When the user stops dragging the divider, the last setting is set to the prior setting for the 
dividerLocation property, not to the initial last value (prior current value) when the drag started. As 
the divider is being dragged, the current value travels first to the last value and then to the prior 
last value. When the dragging stops, the final last setting (29 in this case) is set to the initial last 
setting to reflect the current value when the dragging started. The last three sets of output reflect 


the changes after pressing the one-touch expandable button. 


Current: 11 


Last: 


Last: 


Last: 


Last: 


Last: 


Last: 


Last: 


Last: 


Last: 


1. 


Prior last: 0 
Current: 12 


1 


Prior last: -1 
Current: 12 


12 


Prior last: 11 
Current: 12 


11 


Prior last: 12 
Current: 15 


12 


Prior last: 11 
Current: 15 


15 


Prior last: 12 
Current: 15 


12 


Prior last: 15 
Current: 112 


15 


Prior last: 12 
Current: 112 
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Prior last: 15 
Current: 112 
Last: 15 

Prior last: 112 


Note The BOTTOM, DIVIDER, LEFT, RIGHT, and TOP constants of the JSplitPane class aren't for 
PropertyChangeListener support. Instead, they're internal constraints used by the add(Component 
component, Object constraints) method. 


Customizing a JSplitPane Look and Feel 


Each installable Swing look and feel provides a different JSplitPane appearance and set of 
default UTResource values for this component. Figure 11-9 shows the appearance ofthe JSplitPane 
container for the preinstalled set of look and feel types: Motif, Windows, and Ocean. 


-l0/x 


Motif 
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lo/xi 
Top 


EA 


Ocean 


Figure 11-9. JSplitPane under the different look and feel types 


The available set ofUITResource-related properties for a JSplitPane is shown in Table 11-3. 
For the JSplitPane component, there are 25 different properties, including 3 specific to the divider. 
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Table 11-3. JSplitPane UlResource Elements 


Property String 
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JTabbedPane Class 


itPane. 
itPane. 
itPane. 
itPane. 
itPane. 
itPane. 
itPane. 
itPane. 
itPane. 
itPane. 
itPane. 
itPane. 
itPane. 
itPane. 
itPane. 
itPane. 
itPane. 
itPane. 
itPane. 


itPane. 


itPane.supportsOneTouchButtons 


actionMap 

activeThumb 
ancestorInputMap 
background 

border 
center0neTouchButtons 
darkShadow 
dividerFocusColor 
dividerSize 
foreground 

highlight 
leftButtonText 
oneTouchButtonOffset 
oneTouchButtonSize 
oneTouchButtonsOpaque 
oneTouchExpandable 
oneTouchOffset 
rightButtonText 
shadow 


size 


itPaneDivider.border 


itPaneDivider.draggingColor 


itPaneDivider.oneTouchButtonSize 


itPaneUl 
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Object Type 
ActionMap 
Color 
InputMap 
Color 
Border 
Boolean 
Color 
Color 
Integer 
Color 
Color 
String 
Integer 
Integer 
Boolean 
Boolean 
Integer 
String 
Color 
Integer 
Boolean 
Border 
Color 
Integer 
String 


The JTabbedPane class represents the ever-popular property sheet to support input or output 
from multiple panels within a single window in which only one panel is shown at a time. Using 
JTabbedPane is like using the CardLayout manager, except with added support for changing 
cards built in. While CardLayout is a LayoutManager, JTabbedPane is a full-fledged Container. In 
case you're not familiar with property sheets, tabbed dialog boxes, or tabbed panes (all alternate 
names for the same thing), Figure 11-10 shows a set of tabs from the original SwingSet demo 
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that comes with the JDK 1.2 version of the Swing classes. (This version is more appropriate 
than the current one for demonstrating the features of JTabbedPane described in this section.) 


¡File Options The Swing Team Choosers Dialogs 


SplitPane | TableView | Plain Text E Treeview 


coo 
Swing! | vns | rasozitons | roger | crecioses | Lao | ones 


Figure 11-10. Sample JTabbedPane screen 


To help the JTabbedPane manage which Component (tab) is selected, the model for the 
container is an implementation ofthe SingleSelectionModel interface or, more precisely, a 
DefaultSingleSelectionModel instance. (SingleSelectionModel and DefaultSingleSelectionModel 
were described with the menuing classes in Chapter 6.) 


Creating a JTabbedPane 


There are only three constructors for the JTabbedPane: 


public JTabbedPane() 
JTabbedPane tabbedPane = new JTabbedPane(); 


public JTabbedPane(int tabPlacement) 
JTabbedPane tabbedPane = new JTabbedPane(JTabbedPane.RIGHT); 


public JTabbedPane(int tabPlacement, int tabLayoutPolicy) 
JTabbedPane tabbedPane = 
new JTabbedPane(JTabbedPane.RIGHT, JTabbedPane.SCROLL_TAB_LAYOUT); 


395 


396 


CHAPTER 11 + ADVANCED SWING CONTAINERS 


The configurable options are the placement of the tabs used to change which component 
to display and the tab layout policy for when there are too many tabs to span one virtual row 
(which could be a column). By default, tabs are at the top of the container and will wrap to 
multiple rows when too many exist for the container width. However, you can explicitly specify 
a location with one of the following constants of JTabbedPane: TOP, BOTTOM, LEFT, or RIGHT or 
configure the layout policy with one of SCROLL_TAB_LAYOUT or WRAP_TAP_LAYOUT. Figure 11-11 
shows the screen from Figure 11-10 with the other three tab placements. Figure 11-12 shows 
the screen with the scroll tab layout. 


Right 


Figure 11-11. JTabbedPane tab placement options 


FCaution Setting the tab placement to something other than the equivalent values for the JTabbedPane 
constants of TOP, BOTTOM, LEFT, or RIGHT, or the layout policy to something other than the equivalent of 
SCROLL_TAB_LAYOUT or WRAP_TAP_LAYOUT, will cause an 111egalArgumentException to be thrown. 
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Figure 11-12. JTabbedPane with the scroll tab layout 


Adding and Removing Tabs 


Once you've created the basic JTabbedPane container, you need to add panels that make up the 
sheets or pages of the JTabbedPane. You can add panels in either one of two basic ways. 

Il you're visually creating your interface with a tool like JBuilder or Eclipse, the user inter- 
face builder will use the familiar add() methods of Container to add a Component as a panel. The 
panel added uses component. getName() as the default title. However, you shouldn't use the various 
add() methods if you're programming by hand. 

The more appropriate way to add components or panels to create tabs is with any of the 
addTab() or insertTab() methods listed next. Any or all of the arguments other than the 
component and the position index of insertTab() can be null. (Passing null as the Component 
argument causes a NullPointerException to be thrown at runtime.) The displayed icon and 
tooltip settings have no default values. 


+ public void addTab(String title, Component component) 
+ public void addTab(String title, Icon icon, Component component) 
+ public void addTab(String title, Icon icon, Component component, String tip) 


* public void insertTab(String title, Icon icon, Component component, String tip, 
int index) 
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When using addTab(), the tab is added to the end, which is the farthest right position for a 
set of top or bottom tabs, or at the very bottom for tabs positioned on the left or right side, 
potentially reversing sides, depending on component orientation. 

After creating a panel, you can change its title, icon, mnemonic, tooltip, or component on 
a particular tab with one of the setXXXAt() methods: 


+ public void setTitleAt(int index, String title) 

+ public void setIconAt(int index, Icon icon) 

+ public void setMnemonicAt(int index, int mnemonic) 

+ public void setDisplayedMnemonicIndexAt(int index, int mnemonicIndex) 


+ public void setToolTipTextAt(int index, String text) 


+ public void setComponentAt(int index, Component component) 


Tip The displayed mnemonic index refers to which time a particular character in the title should be high- 
lighted. For instance, if you wanted the second fin title to be the highlighted mnemonic, you would set the 
mnemonic character to KeyEvent .VK_T, with setMnemonicAt (), and the mnemonic index to be 2, with 
setDisplayedMnemonicIndexaAt(). 


In addition, you can change the background or foreground of a specific tab, enable or 
disable a specific tab, or have a different disabled icon with additional setXXXAt () methods: 


+ public void setBackgroundAt(int index, Color background) 

+ public void setForegroundAt(int index, Color foreground) 

+ public void setEnabledAt(int index, boolean enabled) 

+ public void setDisabledIconAt(int index, Icon disabledIcon) 


To remove a tab, you can remove a specific tab with removeTabAt (int index), 
remove(int index), or remove(Component component). In addition, you can remove all tabs 
with removeAl11(). 


JTabbedPane Properties 


Table 11-4 shows the 11 properties of JTabbedPane. Because many of the setter/getter methods of 
JTabbedPane specify an index parameter, they aren't true properties in the literal sense. 
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Table 11-4. JTabbedPane Properties 


Property Name Data Type Access 
accessibleContext AccessibleContext Read-only 
changeListeners ChangeListener[ ] Read-only 

model SingleSelectionModel Read-write bound 
selectedComponent Component Read-write 
selectedIndex int Read-write 
tabCount int Read-only 
tablLayoutPolicy int Read-write-bound 
tabPlacement int Read-write bound 
tabRunCount int Read-only 

UI TabbedPaneUI Read-write bound 
UlClassID String Read-only 


You can programmatically change the displayed tab by setting either the selectedComponent or 
the selectedIndex property. 

The tabRunCount property represents the number of rows (for top or bottom tab placement) 
or columns (for right or left placement) necessary to display all the tabs. 


Caution Changing the LayoutManager for the JTabbedPane will throw an exception when it comes 
time to displaying the container. In other words, don't do it. 


Listening for Changing Tab Selection 


If you're interested in finding out when the selected tab changes, you need to listen for changes 
to the selection model. This is done by your attaching a ChangeListener to the JTabbedPane (or 
directly to the SingleSelectionModel). The registered ChangeListener reports when the selection 
model changes, as the model changes when the selected panel changes. 

The program shown in Listing 11-3 demonstrates listening for changes to the selected tab 
and displays the title of the newly selected tab. 
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Listing 11-3. Listening for Selected Tab Changes 


import javax.swing.*; 
import javax.swing.event.*; 
import java.awt.*; 

import java.awt.event.*; 


public class TabSample ( 

static Color colors[] = fColor.RED, Color.ORANGE, Color.YELLOW, 
Color.GREEN, Color.BLUE, Color.MAGENTA); 

static void add(JTabbedPane tabbedPane, String label, int mnemonic) £ 
int count = tabbedPane.getTabCount (); 
JButton button = new JButton(label); 
button.setBackground(colors[count]); 
tabbedPane.addTab(label, new DiamondIcon(colors[count]), button, label); 
tabbedPane.setMnemonicAt(count, mnemonic); 


J 


public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("Tabbed Pane Sample"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


JTabbedPane tabbedPane = new JTabbedPane(); 

tabbedPane.setTablLayoutPolicy(JTabbedPane.SCROLL_TAB_LAYOUT); 

String titles[] = ("General", "Security", "Content", "Connection", 
"Programs", "Advanced"); 

int mnemonic[] = (KeyEvent.VK_G, KeyEvent.VK_S, KeyEvent.VK_C, 
KeyEvent.VK_0, KeyEvent.VK_P, KeyEvent.VK_A); 

for (int i=0, n=titles.length; i<n; i++) ( 
add(tabbedPane, titles[i], mnemonic[i]); 

J 


Changelistener changeListener = new Changelistener() ( 
public void stateChanged(ChangeEvent changeEvent) ( 
JTabbedPane sourceTabbedPane = (JTabbedPane)changeEvent.getSource(); 
int index = sourceTabbedPane.getSelectedIndex(); 
System.out.println ("Tab changed to: " + 
sourceTabbedPane.getTitleAt(index)); 
j 
E 


tabbedPane.addChangeListener(changelistener); 
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frame.add(tabbedPane, BorderLayout.CENTER); 
frame.setSize(400, 150); 
frame.setVisible(true); 
J 
5 
EventQueue.invokeLater(runner); 
y 
J 


Customizing a JTabbedPane Look and Feel 


Each installable Swing look and feel provides a different JTabbedPane appearance and set of 
default UIResource values for the JTabbedPane component. Figure 11-13 shows the appearance 
ofthe JTabbedPane container for the preinstalled set oflook and feel types: Motif, Windows, and 
Ocean. Several items are specific to the look and feel: how the JTabbedPane appears when the 
set of available tabs is too wide for the display, how it responds when a user selects a tab in a 
back row, howit displays the tooltip, and howit displays the scroll tab layout. 
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Figure 11-13. JTabbedPane under the different look and feel types 
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The available setofUIResource-related properties for a JTabbedPane is shown in Table 11-5. For 
the JTabbedPane component, there are 34 different properties. 


Table 11-5. JTabbedPane UlResource Elements 


Property String Object Type 
TabbedPane.actionMap ActionMap 
TabbedPane.ancestorInputMap InputMap 
TabbedPane.background Color 
TabbedPane.borderHightlightColor Color 
TabbedPane.contentAreaColor Color 
TabbedPane.contentBorderInsets Insets 
TabbedPane. contentOpaque Boolean 
TabbedPane.darkShadow Color 
TabbedPane. focus Color 
TabbedPane.focusInputMap InputMap 
TabbedPane. font Font 
TabbedPane. foreground Color 
TabbedPane.highlight Color 
TabbedPane. light Color 
TabbedPane.opaque Boolean 
TabbedPane.selected Color 
TabbedPane.selectedForeground Color 
TabbedPane.selectedTabPadInsets Insets 
TabbedPane.selectHighlight Color 
TabbedPane.selectionFollowsFocus Boolean 
TabbedPane. shadow Color 
TabbedPane.tabAreaBackground Color 
TabbedPane.tabAreaTnsets Insets 
TabbedPane.tabInsets Insets 
TabbedPane.tabRunOverlay Integer 
TabbedPane.tabsOpaque Boolean 
TabbedPane.tabsOverlapBorder Boolean 
TabbedPane.textIconGap Integer 


TabbedPane.unselectedBackground Color 
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Table 11-5. JTabbedPane UlResource Elements (Continued) 


Property String Object Type 
TabbedPane.unselectedTabBackground Color 
TabbedPane.unselectedTabForeground Color 
TabbedPane.unselectedTabHighlight Color 
TabbedPane.unselectedTabShadow Color 
TabbedPaneUI String 


JScrollPane Class 


Swing's JScrollPane container provides for the display of a large component within a smaller 
display area, with scrolling support (ifnecessary) to get to the parts currently invisible. Figure 11-14 
shows one such implementation, in which the large component is a JLabel with an ImageIcon 
onit. 


Figure 11-14, JScrollPane example 


Identifying the component to be scrolled can be done in one of two ways. Instead of adding 
the component to be scrolled directly to the JScrol11Pane container, you add the component to 
another component, a JViewport, already contained within the scroll pane. Alternatively, you 
can identify the component at construction time, by passing it into the constructor. 


Icon icon = new Imagelcon("dog.jpg"); 

JLabel label = new JLabel (icon); 

JScrollPane jScrollPane = new JScrollPane(); 
jscrollPane.setViewportView(label); 

// or 

JScrollPane jScrollPane2 = new JScrollPane(label); 


Once you've added the component into the JScrol1Pane, users can use the scrollbars to 
see the parts of the large component that aren't visible within the inner area ofthe JScroll1Pane. 

In addition to giving you the means to set the scrollable component for the JScrollPane, a 
display policy determines if and when scrollbars are shown around the JScrollPane. Swing's 
JScrollPane maintains separate display policies for the horizontal and vertical scrollbars. 
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Besides enabling you to add the JViewport and two JScrol1Bar components for scrolling, 
the JScroll1Pane allows you to provide two more JViewport objects for row and column headers 
and four Component objects to display in the scroll pane corners. The placement of all these 
components is managed by the ScrollPaneLayout manager, introduced in Chapter 10 and 
described more fully here. The actual JScrol1Bar components used by JScroll1Pane are a 
subclass of JScrollBar called JScrollPane.ScrollBar. They are used instead of the regular 
JScrol1Bar to properly handle scrolling the component inside the inner JViewmport, when that 
component implements the Scrollable interface. 

To help you see how all the components fit within the JScrol1Pane, Figure 11-15 demon- 
strates how the ScrollPaneLayout positions the various pieces. 
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Figure 11-15. ScrollPaneLayout regions 


Caution The JScro11Pane component supports scrolling only lightweight components. You should not 
add regular, heavyweight AWT components to the container. 


Creating a JScrollPane 


There are four JScrol1Pane constructors: 
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public JScrollPane() 
JScrollPane scrollPane = new JScrollPane(); 


public JScrollPane(Component view) 

Icon icon = new Imagelcon("largelmage.jpg"); 

JLabel imagelabel = new JLabel(icon); 

JScrollPane scrollPane = new JScrollPane(imageLabel); 


public JScrollPane(int verticalScrollBarPolicy, int horizontalScrollBarPolicy) 
JScrollPane scrollPane = new 
JScrollPane(JScrollPane.VERTICAL SCROLLBAR ALWAYS, 
JScrollPane.HORIZONTAL SCROLLBAR ALWAYS); 


public JScrollPane(Component view, int verticalScrollBarPolicy, 
int horizontalScrollBarPolicy) 

JScrollPane scrollPane = new JScrollPane(imagelabel, 
JScrollPane.VERTICAL_SCROLLBAR_ALWAYS, 
JScrollPane.HORIZONTAL SCROLLBAR ALWAYS); 


These offer the options of preinstalling a component to scroll and configuring the scrolling 
policies of the individual scrollbars. By default, the scrollbars are shown only when needed. 
Table 11-6 shows the JScrol1Pane constants used to explicitly set the policies for each scrollbar. 
Using any other nonequivalent setting results in an I1legalArgumentException being thrown. 


Table 11-6. JScrollPane Scrollbar Policies 


Policy Type Description 

VERTICAL_SCROLLBAR_AS NEEDED Displays designated scrollbar if viewport is too small 
to display its entire contents 

HORIZONTAL_SCROLLBAR_AS_ NEEDED Displays designated scrollbar if viewport is too small 
to display its entire contents 

VERTICAL _SCROLLBAR_ALWAYS Always displays designated scrollbar 

HORIZONTAL_SCROLLBAR_ALWAYS Always displays designated scrollbar 

VERTICAL_SCROLLBAR_NEVER Never displays designated scrollbar 

HORIZONTAL_SCROLLBAR_NEVER Never displays designated scrollbar 


The next section explains howto add or change the component after creating a JScroll1Pane. 
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Changing the Viewport View 


If you've created a JScrollPane with an associated component to scroll, you just need to add 
the JScrol1Pane to the display, and it's ready to go. If, however, you didn't associate a compo- 
nent at creation time, or just want to change it later, there are two ways to associate a new 
component to scroll. First, you can directly change the component to scroll by setting the 
viewportView property: 


scrollPane.setViewportView(dogLabel); 


The other way of changing the component to scroll involves centering the JViewport 
within the JScrollPane and changing its view property: 


scrollPane.getViewport().setView(dogLabel); 


You'll learn more about JViewport components in the “JViewport Class” section later in 
this chapter. 


Scrollable Interface 


Unlike the AWT components such as List, which automatically provide a scrollable area when the 
choices are too numerous to display at once, Swing components JList, JTable, JTextComponent, 
and JTree don't automatically provide scrolling support. You must create the component, add 
itto a JScrollPane, and then add the scroll pane to the screen. 


Jlist list = new Jlist(...); 
JScrollPane scrollPane = new JScrollPane(list); 
aFrame.add(scrollPane, BorderLayout.CENTER); 


The reason that adding a component to a JScrol1Pane works is that each ofthe Swing 
components that might be too large for the screen (and require scrolling support) implements 
the Scrollable interface. With this interface implemented, when you move the scrollbars 
associated with the JscrollPane, the JScrollPane asks the Scrollable component within the 
container for its sizing information to properly position the component based on the current 
scrollbar positions. 

The only time you need to worry about the Scrollable interface is when you're creating 
a new custom component that requires scrolling support. The following is the Scrollable 
interface definition. 


public interface Scrollable ( 

public Dimension getPreferredScrollableViewportSize(); 

public boolean getScrollableTracksViewportHeight(); 

public boolean getScrollableTracksViemportWidth(); 

public int getScrollableBlockIncrement(Rectangle visibleRect, int orientation, 
int direction); 

public int getScrollableUnitIncrement(Rectangle visibleRect, int orientation, 
int direction); 


If you create a custom Scrollable component and then place that component in a 
JScrol1Pane, it will respond appropriately when the scrollbars for the JScrol1Pane or the 


mouse wheel are moved. 


JScrollPane Properties 


CHAPTER 11 


Table 11-7 shows the 19 properties of JScrol1Pane. 


Table 11-7. JScrollPane Properties 


Property Name 


accessibleContext 
columnHeader* 
columnHeaderView 
componentOrientation 
horizontalScrollBar* 
horizontalScrollBarPolicy* 
layout 

rowHeader* 

rowHeaderView 

UI 

UlClassID 

validateRoot 
verticalScrollBar* 
verticalScrollBarPolicy* 
viewmport* 

viewportBorder 
viewportBorderBounds 
viewportView 


wheelScrollingEnabled 


* These properties directly map to properties of the Scrol11PaneLayout manager used by the JScro11Pane. 
Changing one of these properties for a JScro11Pane causes its layout manager to change accordingly. 


Caution An attempt to change the layout property of JScro11Pane to something other than a 
ScrollPaneLayout instance or null will throw a ClassCastException at runtime, because the 


Data Type 


AccessibleContext 
JViewport 
Component 
ComponentOrientation 
JScrollBar 

int 

LayoutManager 
JViewport 
Component 
ScrollPaneUI 
String 

boolean 
JScrollBar 

int 

JViewport 

Border 

Rectangle 
Component 


boolean 
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Access 
Read-only 


Read-write bound 
Write-only 
Write-only bound 
Read-write bound 
Read-write bound 
Write-only 
Read-write bound 
Write-only 
Read-write bound 
Read-only 
Read-only 
Read-write bound 
Read-write bound 
Read-write bound 
Read-write bound 
Read-only 
Write-only 


Read-write bound 


layout manager used by a JScrollPane must be a Scrol1PaneLayout. 
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Working with ScrollPaneLayout 


The JScrollPane relies on the ScrollPaneLayout manager for the positioning of components 
within the container. Whereas most layout managers are designed to lay out any type of compo- 
nent, all but four regions of Scrol1PaneLayout accept a component of a specific type. Table 11-8 
shows the type of component that can go into each of the regions shown in Figure 11-15. 


Table 11-8. ScrollPaneLayout Locations 


Location Data Type Description 

COLUMN_HEADER JViewport Usually empty. If main content is a table, serves as column 
headers that won't scroll as vertical scrollbar is moved. 

HORIZONTAL_SCROLLBAR JScrollBar A scrollbar for the main content region placed below that 
region. 

LOWER_LEFT_CORNER Component Usually empty. For a graphic in the lower-left corner. 

LOWER_RIGHT_CORNER Component Usually empty. For a graphic in the lower-right corner. 

ROW_HEADER JViewport Usually empty. If main content is a table, serves as row 
labels that won't scroll when horizontal scrollbar is 
moved. 

UPPER_LEFT_CORNER Component Usually empty. For a graphic in the upper-left corner. 

UPPER_RIGHT_CORNER Component Usually empty. For a graphic in the upper-right corner. 

VERTICAL_SCROLLBAR JScrollBar A scrollbar for the main content region, placed to the right 
of the content area. 

VIEWPORT JViewport The main content area. 


Note The corners have two sets of constants. For internationalization support, you can use 
LOWER_LEADING CORNER, LOWER_TRAILING CORNER, UPPER_LEADING_CORNER, and 
UPPER_TRAILING_ CORNER, which deal with component orientation for you. For left-to-right 
component orientation (United States locale), leading ¡is left, and trailing is right. 


As designed, the layout manager describes the screen layout necessary to support a main 
content area (VIEWPORT) that's too large for the available space. Scrollbars for navigating 
through the area can be placed to the right of the content area (VERTICAL_SCROLLBAR) or below 
it (HORIZONTAL_SCROLLBAR). Fixed headers that don't scroll can be placed above the content area 
(COLUMN_HEADER) or to its left (ROW_HEADER). The four corners (*_CORNER) are configurable to 
display any type of component, which are typically labels with images on them; however, any 
component can be placed there. 
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Note Some developers think of Scro11PaneLayout as a GridBagLayout with customized constraints 
(and restricted contents). Under normal circumstances, most developers won't use Scrol1PaneLayout 
outside a JScrol1Pane. 


Working with JScrollPane Headers and Corners 


As Figure 11-15 and Table 11-8 demonstrate, many different regions exist within the JScrol1Pane. 
Normally, you work with only the central view, and let the two scrollbars do theirthing. In addition, 
when working with the JTable component (described in Chapter 18), the table automatically 
places the column labels within the column header region when placed within a JScroll1Pane. 

You can also manually add or change the column header or row header for a JScrol1Pane. 
Although you can completely replace the JViewmport in these areas, it's easier to just set the 
columnHeaderView or rowHeaderView property to the Component for the area. This action will 
place the component within a JViewport for you. 

To place a component in one of the corners of the JScrol1Pane, you need to call the 
setCorner(String key, Component corner) method, where key is one of the following 
constants from JScrollPane: LONER_LEFT_CORNER, LOWER_RIGHT_CORNER, UPPER_LEFT_CORNER, 
or UPPER_RIGHT_CORNER. 

Working with corners can be tricky. A corner component is displayed only if the two 
components at a right angle from the corner are currently shown. For instance, suppose you 
place a company logo within a label in the lower-right corner, and the scrollbar policy for both 
scrollbars is to show only when necessary. In that case, if one scrollbar were not needed, the 
logo in the corner wouldn't be shown. As another example, if a JScrollPane had a column 
header showing but didn't have a row header, any component in the upper-left corner would 
not be shown. 

Therefore, just because you've set a corner to a component (as with scrollPane. setCorner 
(IScrollPane.UPPER_LEFT_CORNER, logoLabel)), don't expect it to be always or automatically 
shown. Moreover, as Figure 11-16 shows, the neighboring areas control the size of the corner. 
Don't assume a corner component can be as large as necessary. That's because its minimum, 
preferred, and maximum sizes are completely ignored. In Figure 11-16, the actual image used 
to create the corner component is larger than the space used. 
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Figure 11-16. A JScrollPane with a corner component and row and column headers 


Note Changing a corner of a JScro11Pane acts like a bound property where the property name is one of 
the corner keys shown in Table 11-8. 
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Resetting the Viewport Position 


At times, you may want to move the contents of the inner view to the upper-left corner ofthe 
JScrollPane. This change may be needed because the view changed, or because some event 
happened that requires the viewport component to return to the origin ofthe JScroll1Pane. 
The simplest way of moving the view is to adjust the position of the scrollbar thumbs of the 
JScrol1Pane. Setting each scrollbar to its minimum value effectively moves the view of the 
component to the component's upper-left corner. The ActionListener shown in Listing 11-4 
can be associated with a button on the screen or in the corner of the JScrol1Pane, causing the 
contents ofthe JScroll1Pane to return to their origin. 


Listing 11-4. Action to Move JScrollPane to Top 


import java.awt.event.*; 
import javax.swing.*; 


public class JScrollPaneToTopAction implements ActionListener £ 
JScrollPane scrollPane; 
public JScrollPaneToTopAction(JScrollPane scrollPane) ( 
if (scrollPane == null) £ 
throw new IllegalArgumentException( 
"JScrollPaneToTopAction: null JScrollPane"); 


y 
this.scrollPane = scrollPane; 
J 
public void actionPerformed(ActionEvent actionEvent) ( 
JScrollBar verticalScrollBar  = scrollPane.getVerticalScrollBar(); 


JScrollBar horizontalScrollBar = scrollPane.getHorizontalScrollBar(); 
verticalScrollBar.setValue(verticalScrollBar.getMinimum()); 
horizontalScrol1Bar.setValue(horizontalScrollBar.getMinimum()); 


) 


Customizing a JScrollPane Look and Feel 


Each installable Swing look and feel provides a different JScrollPane appearance and set 
of default UTResource values for the component. Figure 11-17 shows the appearance ofthe 
JScrollPane component for the preinstalled set of look and feel types. With a JScrol1Pane, the 
primary differences between the look and feel types are related to the scrollbar's appearance 
and border around the viewport. 

The available set ofUIResource-related properties for a JScrol1Pane is shown in Table 11-9. 
For the JScrol1Pane component, there are ten different properties. Changing the properties 
related to the JScro11Bar will also affect appearance when a scrollbar in a JScrol1Pane is visible. 
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Figure 11-17. JScrollPane under the different look and feel types 


Table 11-9. JScrollPane UlResource Elements 


Property String Object Type 
ScrollPane.actionMap ActionMap 
ScrollPane.ancestorInputMap InputMap 


ScrollPane.ancestorInputMap.RightToLeft  InputMap 


ScrollPane.background Color 
ScrollPane.border Border 
ScrollPane. font Font 

ScrollPane. foreground Color 
ScrollPane.viewportBorder Border 
ScrollPane.viewportBorderInsets Insets 


ScrollPaneUI String 
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JViewport Class 
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The JViewport component is rarely used on its own outside a JScrol1Pane. It normally lives 
within the center of a JScrol1Pane and uses the ViewportLayout manager to respond to posi- 
tioning requests to display a part of a large Component within a smaller space. In addition to 
residing in the center of a JScrollPane, JViewport is also used for the row and column headers 


ofa JScrollPane. 


Creating a JViewport 


There's only one constructor for creating a JViewport: the no-argument version: public 
JViewport(). Once you've created the JVienport, you place a component within it by using 


setView(Component). 


JViewport Properties 


Table 11-10 shows the 13 properties of JViewport. Setting the layout manager to something 
other than ViewportLayout is possible but not recommended because the layout manager 
makes the JViewport do its work properly. 


Table 11-10. JViewport Properties 


Property Name 


accessibleContext 
border 
changeListeners 
extentSize 

insets 
optimizedDrawingEnabled 
scrollMode 

UI 

UIClassID 

view 

viewPosition 
viewRect 


viewSize 


Data Type 


AccessibleContext 
Border 
ChangeListener[ ] 
Dimension 

Insets 

boolean 

int 

Viemportul 

String 

Component 

Point 

Rectangle 


Dimension 


Access 
Read-only 


Write-only 
Read-only 
Read-write 
Read-only 
Read-only 
Read-write 
Read-write bound 
Read-only 
Read-write 
Read-write 
Read-only 


Read-write 


Because of scrolling complexity and for performance reasons, the JViewport doesn't support 
a border. Trying to change the border to a non-nul1 value with setBorder(Border) throws an 
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I1llegalArgumentException. Because there can't be a border, the insets property setting is always 
(0, O, O, 0). Instead of displaying a border around the JViewport, you can display a border around 
the component within the view. Simply place a border around the component, or place the 
component inside a JPanel with a border before adding itto the JViewport. Ifyou do place a 
border around the component, the border would be seen only if that part of the component is 
visible. Ifyou don't want the border to scroll, you must place the JViewport within a component 
such as a JScrol1Pane that has its own border. 


Tip To set the background color of what appears in the JScro11Pane, you need to set the background 
color of the viewport: aScrol1Pane.getViewport().setBackground(newColor). 


The size of the view (viewSize property) is based on the size of the component (view property) 
within the JViewport. The view position (viewPosition property) is the upper-left corner ofthe 
view rectangle (viewRect property), where the rectangle's size is the extent size (extentSize 
property) ofthe viewport. Ifthat's confusing, Figure 11-18 should help you see where all these 
properties lie within the JVienport. 


viewSize property ——_—_—_—_—_—_—_——= 
(width) 


viewPosition 


viewSize property 
(height) 


JViewPort EN . extentSize property 
DS (width) ca 


extentSize property 
(height) 


viewRect 


Figure 11-18. Visualizing JViewport properties 
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The scrollMode property can be set to one of the class constants shown in Table 11-11. 
In most cases, you can rely on the fastest and default BLIT_SCROLL_MODE mode. 


Table 11-11. JViewport Scroll Modes 


Scroll Mode Description 

BACKINGSTORE_SCROLL_MODE A deprecated but supported mode that relies on a buffer 
for scrolling 

BLIT_SCROLL_MODE The default mode, which relies on Graphics .copyArea() 

SIMPLE_SCROLL_MODE Redraws entire area 


To move the visible part of the view around, just change the viewPosition property. This 
moves the vienRect, allowing you to see a different part of the view. To demonstrate this, the 
program shown in Listing 11-5 attaches keyboard accelerators to the JViewport so that you 
can use the arrow keys to move around the view. (Normally, the JScrol1Pane would get these 
keyboard actions.) The majority ofthe code is necessary to set up the appropriate input/action 
maps. The boldfaced line of code is the one necessary to move the view. 


Listing 11-5. Keyboard Movement Control in a JViewport 


import javax.swing.*; 
import java.awt.*; 
import java.awt.event.*; 


public class MoveViewSample ( 


public static final int INCREASE = 0; // direction 
public static final int DECREASE = 1; // direction 
public static final int X_AXIS  = 0; // axis 
public static final int Y AXIS  = 1; // axis 
public static final int UNIT = 0; // type 
public static final int BLOCK = 1; // type 


static class MoveAction extends AbstractAction 4 
JViewport viewport; 
int direction; 
int axis; 
int type; 
public MoveAction(JViewport viewport, int direction, int axis, int type) ( 
if (viewport == null) ( 
throw new IllegalArgumentException ("null viewport not permitted"); 


J 
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this.viewport = viewport; 
this.direction = direction; 
this.axis = axis; 
this.type = type; 
h 
public void actionPerformed(ActionEvent actionEvent) ( 
Dimension extentSize = viewport.getExtentSize(); 
int horizontalMoveSize = 0; 
int verticalMoveSize = 0; 
1f (axis == X_ AXIS) ( 
if (type == UNIT) £ 
horizontalMoveSize = 1; 
j else ([ // type == BLOCK 
horizontalMoveSize = extentSize.width; 
) 
j else ([ // axis == Y_AXIS 
if (type == UNIT) £ 
verticalMoveSize = 1; 
j else ([ // type == BLOCK 
verticalMoveSize = extentSize.height; 
l 
4 
if (direction == DECREASE) € 
horizontalMoveSize = -horizontalMoveSize; 
verticalMoveSize = -verticalMoveSize; 
A 
// Translate origin by some amount 
Point origin = viewport.getViewPosition(); 
origin.x += horizontalMoveSize; 
origin.y += verticalMoveSize; 
// Set new viewing origin 
vienport.setViewPosition(origin); 
) 
) 


public static void main(String args[]) ( 
Runnable runner = new Runnable() £ 
public void run() £ 

JFrame frame = new JFrame("JViewport Sample"); 
frame.setDefaultClose0peration(JFrame.EXIT_ON CLOSE); 
Icon icon = new Imagelcon("dog.;jpg"); 
JLabel doglabel = new JLabel(icon); 
JViemport viemport = new JViewport(); 
vienport.setView(dogLabel); 
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InputMap inputMap = viewport.getInputMap(JComponent.WHEN_IN_FOCUSED_WINDOW) ; 
ActionMap actionMap = viewport.getActionMap(); 


// Up key moves view up unit 
Action upKeyAction = 

new MoveAction(viewport, DECREASE, Y AXIS, UNIT); 
KeyStroke upKey = KeyStroke.getKeyStroke("UP"); 
inputMap.put(upKey, "up”); 
actionMap.put("up", upKeyAction); 


// Down key moves view down unit 
Action downKeyAction = 

new MoveAction(viewport, INCREASE, Y AXIS, UNIT); 
KeyStroke downKey = KeyStroke.getKeyStroke("DOWN"); 
inputMap.put(downKey, "down"); 
actionMap.put("down", downKeyAction); 


// Left key moves view left unit 
Action leftKeyAction = 

new MoveAction(viewport, DECREASE, X_AXIS, UNIT); 
KeyStroke leftKey = KeyStroke.getKeyStroke("LEFT"); 
inputMap.put(leftKey, "left"); 
actionMap.put("left", leftKeyAction); 


// Right key moves view right unit 
Action rightKeyAction = 

new MoveAction(viewport, INCREASE, X_AXIS, UNIT); 
KeyStroke rightKey = KeyStroke.getKeyStroke("RIGHT"); 
inputMap.put(rightKey, "right"); 
actionMap.put("right", rightKeyAction); 


// PgUp key moves view up block 
Action pgUpKeyAction = 

new MoveAction(viewport, DECREASE, Y AXIS, BLOCK); 
KeyStroke pgUpKey = KeyStroke.getKeyStroke("PAGE_UP"); 
inputMap.put (pgUpKey, "pgUp”); 
actionMap.put("pgUp", pgUpKeyAction); 


// PgDn key moves view down block 
Action pgDnKeyAction = 

new MoveAction(viewport, INCREASE, Y AXIS, BLOCK); 
KeyStroke pgDnKey = KeyStroke.getKeyStroke("PAGE_ DOWN"); 
inputMap.put(pgDnKey, "pgDn"); 
actionMap.put("pgDn", pgDnKeyAction); 


CHAPTER 11 ADVANCED SWING CONTAINERS 


// Shift-PgUp key moves view left block 
Action shiftPgUpKeyAction = 

new MoveAction(viewport, DECREASE, X_AXIS, BLOCK); 
KeyStroke shiftPgUpKey = KeyStroke.getKeyStroke("shift PAGE_UP"); 
inputMap.put(shiftPgUpKey, "shiftPgUp"); 
actionMap.put("shiftPgUp", shiftPgUpKeyAction); 


// Shift-PgDn key moves view right block 
Action shiftPgDnKeyAction = 
new MoveAction(viewport, INCREASE, X_AXIS, BLOCK); 
KeyStroke shiftPgDnKey = KeyStroke.getKeyStroke("shift PAGE DOWN"); 
inputMap.put(shiftPgDnKey, "shiftPgDn"); 
actionMap.put("shiftPgDn", shiftPgDnKeyAction); 


frame.add(viewport, BorderLayout.CENTER); 
frame.setSize(300, 200); 
frame.setVisible(true); 
J 
5 
EventQueue.invokelLater(runner); 
l 
J 


Customizing a JViewport Look and Feel 


Each installable Swing look and feel shares the same JViewport appearance with the 
BasicViemportUl. There are no actual appearance differences. However, there still exists 
a set of UIResource-related properties for the JViewmport, as shown in Table 11-12. For the 
JViemport component, there are four such properties. 


Table 11-12. JViewport UlResource Elements 


Property String Object Type 
Viewport .background Color 
Viewport.font Font 
Viewport.foreground Color 
ViewmportUl String 


Summary 


In this chapter, you explored several high-level Swing containers. With the Box class, you can 
more easily utilize the BoxLayout manager to create a single row or column of components, 


honoring the minimum, preferred, and maximum size of the components the best way possible. 


417 


418 


CHAPTER 11 ADVANCED SWING CONTAINERS 


With the JSplitPane component, you can create a row or column consisting of two 
components with a divider in between them to allow an end user to alter the components” 
sizes manually by moving the divider. 

The JTabbedPane container displays only one component from a set of contained compo- 
nents at a time. The displayed component is picked by the user selecting a tab, which can 
contain a title with or without mnemonic, anicon, and a tooltip. This is the popular property 
sheet metaphor commonly seen within applications. 

The JScrollPane and JViewport containers allow you to display a large component within 
a small area. The JScrollPane adds scrollbars to enable an end user to move the visible part 
around, whereas the JViewport doesn't add these scrollbars. 

In Chapter 12, we'll once again examine the individual components within the Swing 
library, including the JProgressBar, JScrol11Bar, and JSlider that share the BoundedRangeModel 
as their data model. 


CHAPTER 12 


Bounded Range Components 


Í, the previous chapter, you saw how JScrol1Pane provides a scrollable region for those situations 
when there isn't sufficient space to display an entire component on screen. Swing also offers 
several components that support some type of scrolling or the display of a bounded range of values. 
The available components are JScroll1Bar, JSlider, JProgressBar, and, in a more limited sense, 
JTextField. These components share a BoundedRangeModel as their data model. The default imple- 
mentation of this data model provided with the Swing classes is the DefaultBoundedRangeModel 
class. 

In this chapter, you'll look at the similarities and differences between these Swing 
components. Let's start with their shared data model, the BoundedRangeModel. 


BoundedRangeModel Interface 


The BoundedRangeModel interface is the Model-View-Controller (MVC) data model shared by 
the components described in this chapter. The interface contains four interrelated properties 
that are necessary to describe a range of values: minimum, maximum, value, and extent. 

The minimum and maximum properties define the limits of the value of the model. The value 
property defines what you might think of as the current setting ofthe model, where the maximum 
setting of the value property is not necessarily the value of the maximum property of the model. 
Instead, the maximum setting that the value property can take is the maximum property less the 
extent property. To help you visualize these properties, Figure 12-1 shows these settings in relation 
to a JScrollBar. Any other purpose of the extent property depends on the component acting 
as the model's view. 


Minimum Value Maximum 


Maximum 
Value 


Extent 


Figure 12-1. BoundedRange properties on a JScrollBar 
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The settings for the four properties must abide by the following ordering: 
minimum <= value <= value+extent <= maximum 


When one of the settings changes, the change may trigger changes to other settings to keep 
the ordering valid. For instance, changing the minimum to a setting between the current value 
plus extent setting and the maximum will decrease the extent and increase the value to keep the 
ordering valid. In addition, the original property change may result in a change to a new setting 
other than the requested setting. Forinstance, attempting to setthe value below the minimum or 
maximum will set the value to the nearest limit of the range. 

The BoundedRangeMode1 interface definition follows: 


public interface BoundedRangeModel ( 
// Properties 

public int getExtent(); 

public void setExtent(int newValue); 

public int getMaximum(); 

public void setMaximum(int newValue); 

public int getMinimum(); 

public void setMinimum(int newValue); 

public int getValue(); 

public void setValue(int newValue); 

public boolean getValuelsAdjusting(); 

public void setValuelsAdjusting(boolean newValue); 

// Listeners 

public void addChangeListener(Changelistener listener); 

public void removeChangeListener(ChangeListener listener); 

// Other Methods 

public void setRangeProperties(int value, int extent, int minimum, 
int maximum, boolean adjusting); 


Although the different settings available for the model are JavaBean properties, when a 
property setting changes, the interface uses Swing's ChangeListener approach instead ofa 
java.beans.PropertyChangeListener. 

The model's valuelsAdjusting property comes into play when the user is performing a 
series of rapid changes to the model, probably as a result of dragging the slider on the screen. 
For someone interested in knowing only when the final value is set for a model, a listener 
would ignore any changes until getValuelIsAdjusting() returns false. 


DefauliBoundedRangeModel Class 


The Swing class actually implementing the BoundedRangeModel interface is DefaultBoundedw»> 
RangeModel. This class takes care ofthe adjustments necessary to ensure the appropriate 
ordering of the different property values. It also manages a ChangeListener list to notify 
listeners when a model change happens. 
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DefaultBoundedRangeModel has two constructors: 


public DefaultBoundedRangeModel () 


public DefaultBoundedRangeModel(int value, int extent, int minimum, int maximum) 


The no-argument version sets up the minimum, value, and extent properties of the model 
to have a setting of 0. The remaining maximum property gets a setting of 100. 

The second constructor version takes four integer parameters, explicitly setting four proper- 
ties. For both constructors, the initial value of the valuelsAdjusting property is false because 
the value of the model isn't yet changing beyond the initial value. 


Note Unless you're sharing a model across multiple components, it generally isn't necessary to create a 
BoundedRangeModel. Even if you're sharing a model across multiple components, you can create just the 
first component and get its BoundedRangeModel model to share. 


As with practically all of the classes that manage their own listener lists, you can ask 
DefaultBoundedRangeModel for the listeners assigned to it. Here, you ask the model for its 
ChangeListener list with getListeners (ChangeListener.class). This returns an array of 
EventListener objects. 


JScrollBar Class 


The simplest ofthe bounded range components is the JScrol11Bar. The JScrol1Bar component 
is used within the JScrollPane container, described in Chapter 11, to control the scrollable 
region. You can also use this component within your own containers, although with the flexibility 
of JScrol1Pane this typically isn't necessary. The one point to remember about JScrollBar, 
however, is that itisn't used for the entry of a value, but solely for the scrolling of a region of 
screen real estate. For the entry of a value, you use the JS1ider component discussed in the 
next section. 


Note The JScrol1Bar within a JScro11Pane is actually a specialized subclass of JScro11Bar that 
properly deals with scrollable components that implement the Scrol11able interface. Although you can 
change the scrollbars of a JScrol1Pane, it's usually unnecessary—and more work than you might think. 


As Figure 12-2 shows, the horizontal JScrol1Bar is composed of several parts. Starting 
from the middle and working outward, you find the scrollbar's thumb—also called a knob or 
slider. The width of the thumb is the extent property from the BoundedRangeModel. The current 
value of the scrollbar is at the left edge of the thumb. To the immediate left and right of the 
thumb are the block paging areas. Clicking to the left of the thumb will decrement the scrollbar's 
value, while clicking to the right increments it. The increased or decreased amount ofthe 
scrollbar's value is the scrollbar's blockIncrement property. 
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Minimum Value Thumb 
Maximum Value 
Block Increment 


Unit Increment 


Block 
Decrement 


Unit 
Decrement 


Extent 
Figure 12-2. Horizontal JScrollBar anatomy 


On the left and right edges of the scrollbar are arrow buttons. When the left arrowis pressed, 
the scrollbar decrements down a unit. The scrollbar's unitIncrement property specifies this 
unit. Typically, this value is one, though it doesn't have to be. To the immediate right ofthe left 
arrow is the minimum value of the scrollbar and the model. In addition to decreasing the value 
with the left arrow, clicking the right arrow causes the scrollbar to increment a unit. To the 
immediate left ofthe right arrow is the scrollbar's maximum range. The maximum value is 
actually a little farther to the left, where this “little farther” is specified by the model's extent 
property. When the thumb is next to the right arrow, this places the scrollbar value of the 
scrollbar at the left edge of the thumb, which is the case with all other positions, no matter 
where the thumb is. 

A vertical JScrol1Bar is composed of the same parts as a horizontal JScroll1Bar, with the 
minimum and decrement parts at the top, and the value designated by the top edge of the 
scrollbar's thumb. The maximum and increment parts are at the bottom. 

As previously mentioned, the model for the JScrol1Bar is the BoundedRangeModel. The 
delegate for the user interface is the Scrol1Barul. 

Now that you've seen the different pieces of a JScroll1Bar, let's see how to use them. 


Creating JScrollBar Components 


There are three constructors for JScroll1Bar: 


public JScrollBar() 
JScrollBar aJScrollBar = new JScrollBar(); 


public JScrollBar(int orientation) 
// Vertical 
JScrollBar aJScrollBar 
// Horizontal 
JScrollBar bJScrollBar = new JScrol1Bar(JScrol1Bar.HORIZONTAL); 


new JScrollBar(JScrollBar.VERTICAL); 


public JScrollBar(int orientation, int value, int extent, int minimum, int maximum) 
// Horizontal, initial value 500, range 0-1000, and extent of 25 
JScrollBar aJScrollBar = new JScrollBar(JScrol1Bar.HORIZONTAL, 500, 25, 0, 1025); 


Creating a JScrol1Bar with no arguments creates a vertical scrollbar with a default data 
model. The model has an initial value of 0, a minimum of 0, a maximum of 100, and an extent 
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of 10. This default model offers a range of only 0 through 90. You can also explicitly set the 
orientation to JScro11Bar.HORIZONTAL or JScrol1Bar.VERTICAL. If you don't like the initial 
model settings provided by the other two constructors, you need to explicitly set everything 
yourself. Ifthe data elements aren't properly constrained, as described in the previous section 
about BoundedRangeMode], an I11egalArgumentException will be thrown, causing the JScrol1Bar 
construction to be aborted. 

Surprisingly missing from the list of constructors is one that accepts a BoundedRangeModel 
argument. If you have a model instance, you can either call setModel (BoundedRangeModel 
nenModel) after creating the scrollbar or get the individual properties from the model when 
creating the scrollbar, as follows: 


JScrollBar aJScrollBar = 
new JScrollBar (JScrollBar.HORIZONTAL, aModel.getValue(), aModel.getExtent(), 
aModel.getMinimum(), aModel.getMaximum()) 


Tip Starting with the 1.3 release of the J2SE platform, scrollbars do not participate in focus traversal. 


Handling Scrolling Events 


Once you've created your JScrol1Bar, it's necessary to listen for changes if you're interested in 
when the value changes. There are two ways of listening: the AWT 1.1 event model way and the 
Swing MVC way. The AWT way involves attaching an AdjustmentListener to the JScrollBar. 
The MVC way involves attaching a ChangeListener to the data model. Each works equally well, 
and both are notified ifthe model changes programmatically or by the user dragging the 
scrollbar thumb. The latter offers more flexibility and is a good choice, unless you're sharing a 
data model across components and need to know which component altered the model. 


Listening to Scrolling Events with an AdjustmentListener 


Attaching an AdjustmentListener to a JScrol1Bar allows you to listen for the user to change the 
setting of the scrollbar. The following code fragments, used for the example shown later in 
Figure 12-3, show how to attach an AdjustmentListener to a JScrollBar to listen for the user 
adjusting the value of the JScrol1Bar. 

First, define the appropriate AdjustmentListener that simply prints out the current value 
of the scrollbar: 


AdjustmentListener adjustmentListener = new AdjustmentListener() ( 
public void adjustmentValueChanged (AdjustmentEvent adjustmentEvent) ( 
System.out.println ("Adjusted: " + adjustmentEvent.getValue()); 
y 
; 


After you've created the listener, you can create the component and attach the listener: 


JScrollBar oneJScrollBar = new JScrollBar (JScrollBar.HORIZONTAL); 
oneJScrollBar.addAdjustmentListener(adjustmentListener); 
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This manner of listening for adjustment events works perfectly well. However, you may 
prefer to attach a ChangeListener to the data model, as described next. 


Listening to Scrolling Events with a ChangeListener 


Attaching a ChangeListenerto a JScrollBar data model provides more flexibility in your program 
designs. With an AWT AdjustmentListener, listeners are notified only when the value of the 
scrollbar changes. On the other hand, an attached ChangeListener is notified when there's any 
change in the minimum value, maximum value, current value, or extent. In addition, because the 
model has a valueIsAdjusting property, you can choose to ignore intermediate change events— 
something you can also do with an AdjustmentListener, via the property ofthe same name in 
the AdjustmentEvent. 

To demonstrate, define a ChangeListener that prints out the current value of the scrollbar 
when the model has finished adjusting, as shown in Listing 12-1. You'll enhance this 
BoundedChangeListener class throughout the chapter. 


Listing 12-1. ChangeListener for BoundedRangeModel 


import javax.swing.*; 
import javax.swing.event.*; 


public class BoundedChangeListener implements ChangeListener ( 
public void stateChanged(ChangeEvent changeEvent) ( 
Object source = changeEvent.getSource(); 
if (source instanceof BoundedRangeModel) ( 
BoundedRangeModel aModel = (BoundedRangeModel)source; 
if (laModel.getValuelsAdjusting()) ( 
System.out.println ("Changed: " + aModel.getValue()); 
y 
) else [ 
System.out.println ("Something changed: " + source); 
J 
J 
y 


Once you create the listener, you can create the component and attach the listener. In this 
particular case, you need to attach the listener to the data model of the component, instead of 
directly to the component. 


Changelistener changeListener = new BoundedChangeListener(); 
JScrollBar anotherJScrollBar = new JScrollBar (JScrollBar.HORIZONTAL); 
BoundedRangeModel model = anotherJScrol1lBar.getModel (); 

model .addChangeListener(changeLlistener); 


The source for the testing program is shown in Listing 12-2. 
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Listing 12-2. JScrollBar Usage Sample 


import javax.swing.*; 
import javax.swing.event.*; 
import java.awt.*; 

import java.awt.event.*; 


public class ScrollBarSample f 
public static void main(String args[]) ( 
Runnable runner = new Runnable() 4 
public void run() £ 

AdjustmentListener adjustmentListener = new AdjustmentListener() ( 

public void adjustmentValueChanged(AdjustmentEvent adjustmentEvent) £ 
System.out.println("Adjusted: " + adjustmentEvent.getValue()); 

) 

5 

JScrollBar oneJScrollBar = new JScrollBar(JScrol1Bar.HORIZONTAL); 

oneJScrol1Bar.addAdjustmentListener(adjustmentListener); 


Changelistener changelListener = new BoundedChangeListener(); 
JScrollBar anotherJScrollBar = new JScrollBar(JScrollBar.HORIZONTAL); 
BoundedRangeModel model = anotherJScrol1Bar.getModel (); 

model .addChangeListener(changelistener); 


JFrame frame = new JFrame("ScrollBars R Us"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
frame.add(oneJScrollBar, BorderLayout.NORTH) ; 
frame.add(anotherJScrollBar, BorderLayout. SOUTH); 
frame.setSize(300, 200); 
frame.setVisible(true); 
) 
5 
EventQueue.invokeLater(runner); 
) 
) 


When you run this program, it shows the two horizontal scrollbars seen in Figure 12-3. 
The output of moving the scrollbars is sent to the console window. 


-10/x) 
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Figure 12-3. Dual JScrollBar listening 
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JScrollBar Properties 


After you've created a JScroll1Bar, it may become necessary to modify its underlying data 
model. You can get the model with the public BoundedRangeModel getModel() method, and 
then modify the model directly. More likely, you would just call the appropriate methods ofthe 
component: 


+ setValue(int newValue), setExtent(int newValue), setMinimum(int newValue) 
+ setMaximum(int newValue) 


These methods act as proxies and redirect any calls to the equivalent model method. 


Caution Although supported, it's not recommended that you modify a JScro11Bar's orientation after 
displaying the component. This could seriously diminish the user's satisfaction and encourage the user to find 
a solution from another vendor! 


In addition to the data model properties, Table 12-1 shows the 16 properties of JScrol1Bar. 


Table 12-1. JScrollBar Properties 


Property Name Data Type Access 
accessibleContext AccessibleContext Read-only 
adjustmentListeners AdjustmentListener[ ] Read-only 
blockIncrement int Read-write bound 
enabled boolean Write-only 

aximum int Read-write 

aximumSize Dimension Read-only 

inimum int Read-write 

inimumSize Dimension Read-only 

odel BoundedRangeModel Read-write bound 
orientation int Read-write bound 
UI ScrollBarul Read-write bound 
UlClassID String Read-only 
unitIncrement int Read-write bound 
value int Read-write bound 
valuelsAdjusting boolean Read-write bound 
visibleAmount int Read-write 
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Customizing a JScrollBar Look and Feel 


Each installable Swing look and feel provides a different JScrol1Bar appearance and set of 
default UTResource values. Figure 12-4 shows the appearance ofthe JScrol1Bar component for 
the preinstalled set of look and feel types: Motif, Windows, and Ocean. 
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Figure 12-4. JScrollBar under different look and feel types 


The available set ofUIResource-related properties for a JScro11Bar is shown in Table 12-2. 
There are 28 different properties. 


Table 12-2. JScrollBar UlResource Elements 


Property String 


scrollbar 


ScrollBar. 
ScrollBar. 
ScrollBar. 
ScrollBar. 
ScrollBar. 
ScrollBar. 
ScrollBar. 
ScrollBar. 
ScrollBar. 
ScrollBar. 
ScrollBar. 
ScrollBar. 
ScrollBar. 
ScrollBar. 
ScrollBar. 
ScrollBar. 
ScrollBar. 
ScrollBar. 


ScrollBar. 


ScrollBar. 


actionMap 
allowsAbsolutePositioning 
ancestorInputMap 
ancestorInputMap.RightToLeft 
background 

border 

darkShadow 

focusInputMap 
focusInputMap.RightToLeft 
foreground 

gradient 

highlight 
maximumThumbSize 
minimumThumbSize 

shadow 

squareButtons 

thumb 

thumbDarkShadow 
thumbHeight 
thumbHighlight 


Object Type 
Color 
ActionMap 
Boolean 
InputMap 
InputMap 
Color 
Border 
Color 
Object[ ] 
InputMap 
Color 
List 
Color 
Dimension 
Dimension 
Color 
Boolean 
Color 
Color 


Integer 


Color 
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Table 12-2. JScrollBar UlResource Elements (Continued) 


Property String Object Type 
ScrollBar.track Color 
ScrollBar.trackForeground Color 
ScrollBar.trackHighlight Color 
ScrollBar.trackHighlightForeground Color 
ScrollBar.width Integer 
ScrollBaruI String 


JSlider Class 


Although the JScro11Bar component is useful for scrolling regions of the screen, it's nota good 
component for getting user input for a range of values. For that purpose, Swing offers the 

JSlider component. In addition to a draggable thumb like the one provided by the JScrol1Bar 
component, the JS1ider component offers visible tick marks and labels to assistin showingthe 
current setting and selecting a new one. Figure 12-5 shows several sample JS1ider components. 
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Figure 12-5. Sample JSlider components 


The JSlider is made up of several pieces. The familiar BoundedRangeModel stores the data 
model for the component, and a Dictionary stores any labels for the tick marks. The user interface 
delegate is the SliderUl. 

Now that you've seen the different pieces of a JSlider, let's find out how to use them. 


Creating JSlider Components 


There are six different constructors for JSlider: 
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public JSlider() 
JSlider aJSlider = new JSlider(); 


public JSlider(int orientation) 

// Vertical 

JSlider aJSlider = new JSlider(JSlider.VERTICAL); 
// Horizontal 

JSlider bJSlider = new JSlider(JSlider.HORIZONTAL); 


public JSlider(int minimum, int maximum) 
// Initial value midpoint / O 
JSlider aJSlider = new JSlider(-100, 100); 


public JSlider(int minimum, int maximum, int value) 
JSlider aJSlider = new JSlider(-100, 100, 0); 


public JSlider(int orientation, int minimum, int maximum, int value) 
// Vertical, initial value 6, range 1-12 (months of year) 
JSlider aJSlider = new JSlider(JSlider.VERTICAL, 6, 1, 12); 


public JSlider(BoundedRangeModel model) 
// Data model, initial value 3, range 1-31, and extent of O 
// JSlider direction changed to vertical prior to display on screen 


DefaultBoundedRangeModel model = new DefaultBoundedRangeModel(3, 0, 1, 31); 


JSlider aJSlider = new JSlider(model); 
aJSlider.setO0rientation(JSlider.VERTICAL); 


Creating a JSlider with no arguments creates a horizontal slider with a default data model. 
The model has an initial value of 50, a minimum of 0, a maximum of 100, and an extent of 0. 
You can also explicitly set the orientation with JSlider.HORIZONTAL or JSlider.VERTICAL, and 
any of the specific model properties, with the various constructors. In addition, you can explicitly 


set the data model for the component. 


If you're using a preconfigured BoundedRangeModel, remember to set the extent to 0 when 
creating the model. If the extent property is greater than 0, then the maximum setting of the 
value property is decreased by that amount, and the value setting will never reach the setting 


ofthe maximum property. 


Caution nitializing the orientation to something not equivalent to VERTICAL or HORIZONTAL throws 
an IllegalArgumentException. All constructor that initialize the data model could throw an 
I1legalArgumentException if the range and initial value fail to abide by the rules of the 


BoundedRangeModel described earlier in the section “BoundedRangeModel Interface.” 
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Handling JSlider Events 


You track changes to a JSl1ider with a ChangeListener. There's no AdjustmentListener, as 
there is with JScrol1Bar (and Scrollbar). The same BoundedChangeListener from the earlier 
JScrol1Bar example could be added to a data model of the JSlider, and you'll then be notified 
when the model changes. 


Changelistener aChangeListener = new BoundedChangeListener(); 
JSlider aJSlider = new JSlider (); 

BoundedRangeModel model = aJSlider.getModel(); 
model.addChangeListener(changeLlistener); 


In addition to attaching a ChangeListener to the model, you can associate the ChangeListener 
directly with the JS1ider itself. This allows you to share the data model between views and 
listen independently for changes. This requires you to modify the preceding listener a bit, 
because the change event source will now be a JSlider instead of a BoundedRangeModel. The 
updated BoundedChangelListener, shown in Listing 12-3, will work for both associations, however. 
The changes are boldfaced in the following listing. 


Listing 12-3. ChangeListener for BoundedRangeModel and JSlider 


import javax.swing.*; 
import javax.swing.event.*; 


public class BoundedChangeListener implements ChangeListener ( 
public void stateChanged(ChangeEvent changeEvent) ( 
Object source = changeEvent.getSource(); 
if (source instanceof BoundedRangeModel) ( 
BoundedRangeModel aModel = (BoundedRangeModel)source; 
if (laModel.getValuelsAdjusting()) ( 
System.out.println ("Changed: " + aModel.getValue()); 
y 
) else if (source instanceof JSlider) ( 
JSlider theJSlider = (JSlider)source; 
if (!theJSlider.getValuelsAdjusting()) ( 
System.out.println ("Slider changed: " + theJSlider.getValue()); 
J 
) else [ 
System.out.println ("Something changed: " + source); 
J 
J 
y 


The association with the slider can now be direct, instead of indirect through the model. 


aJSlider.addChangeListener(changeListener); 
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JSlider Properties 


After you've created a JSlider, you may want to modify its underlying data model. As is the 
case with JScrol1Bar, you can get the model with the public BoundedRangeModel getModel (>) 
method, and then modify the model directly. You can also directly call the methods of the 
component: 


+. setValue(int newValue), setExtent(int newValue), setMinimum(int newValue) 
* setMaximum(int newValue) 


As with JScrol1Bar, these methods act as proxies and redirect any calls to the equivalent 
model method. 
Table 12-3 shows the 19 properties of JSlider. 


Table 12-3. JSlider Properties 


Property Name Data Type Access 
accessibleContext AccessibleContext Read-only 
changeListeners ChangeListener[ ] Read-only 
extent int Read-write 
inverted boolean Read-write bound 
labelTable Dictionary Read-write bound 
majorTickSpacing int Read-write bound 
aximum int Read-write bound 
inimum int Read-write bound 
inorTickSpacing int Read-write bound 
odel BoundedRangeModel Read-write bound 
orientation int Read-write bound 
paintLabels boolean Read-write bound 
paintTicks boolean Read-write bound 
paintTrack boolean Read-write bound 
snapToTicks boolean Read-write bound 
UI Sliderul Read-write bound 
UlClassID String Read-only 
value int Read-write 
valuelsAdjusting boolean Read-write bound 
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Displaying Tick Marks Within a JSlider 


The JSlider component allows you to add tick marks either below a horizontal slider or to the 
right of a vertical slider. These tick marks allow a user to get a rough estimate of the slider's 
value and scale. There can be both major and minor tick marks; the major ones are simply 
drawn to be a little longer. Either or both can be displayed, as well as neither of them, which is 
the default. 


Note Technically, a custom look and feel could place the tick marks anywhere. However, the system- 
provided look and feel types place the ticks below or to the right. 


To display the tick marks, you need to enable their painting with the public void 
setPaintTicks(boolean newValue) method. When called with a setting of true, this method enables 
the painting of minor and major tick marks. By default, the tick spacing for both types of tick 
marks is set to zero. When either is set to zero, that particular ticktype isn't displayed. Because both 
are initially zero, you must change the value of either tick spacing to see any ticks. The public 
void setMajorTickSpacing(int newValue) and public void setMinorTickSpacing(int newValue) 
methods both support this change. 

To demonstrate, Figure 12-6 shows four sliders: one with no ticks, one with aesthetically 
pleasing tick spacing, and two with unconventional tick spacing. It helps ifthe major tick 
spacingis a multiple ofthe minor tick spacing (just as a ruler shows inches, halfinches, quarter 
inches, and so on with different tick lengths). In addition, the tick spacing shouldn't be so 
narrow that the ticks look like a solid block. 


J0/x 
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Figure 12-6. Four JSlider controls demonstrating tick marks 


The source for the example in Figure 12-6 is shown in Listing 12-4. The top slider has no 
ticks. The bottom slider has the aesthetically pleasing major/minor spacing, with minor ticks 
at 5 units and major ones at 25 units. The left slider displays poor spacing with minor ticks at 6 
and major ticks at 25. The right slider has minor ticks at each individual unit, resulting in 
spacing that's much too tight. 
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Listing 12-4. JSlider with Tick Marks 


import javax.swing.*; 
import java.awt.*; 


public class TickSliders ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() 4 
public void run() £ 
JFrame frame = new JFrame("Tick Slider"); 
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frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


// No Ticks 

JSlider jSliderOne = new JSlider(); 
// Major Tick 25 - Minor 5 

JSlider jSliderTwo = new JSlider(); 
jsliderTwo.setMinorTickSpacing(5); 
jsliderTwo.setMajorTickSpacing(25); 
jsliderTwo.setPaintTicks(true); 
jsliderTwo.setSnapToTicks(true); 

// Major Tick 25 - Minor 6 


jsliderThree.setMinorTickSpacing(6); 
jsliderThree.setMajorTickSpacing(25); 
jsliderThree.setPaintTicks(true); 


// Major Tick 25 - Minor 1 
jsliderFour.setMinorTickSpacing(1); 
jsliderFour.setMajorTickSpacing(25); 
jsliderFour.setPaintTicks(true); 


frame.add(jSliderO0ne, BorderLayout.NORTH); 
frame.add(jSliderTwo, BorderLayout. SOUTH); 
frame.add(jSliderThree, BorderLayout.WEST); 
frame.add(jSliderFour, BorderLayout.EAST); 
frame.setSize(300, 200); 
frame.setVisible(true); 
) 
E 
EventQueue.invokelLater(runner); 
) 
h 


JSlider jSliderThree = new JSlider(JSlider.VERTICAL); 


JSlider jSliderFour = new JSlider(JSlider.VERTICAL); 
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Snapping the JSlider Thumb into Position 


One additional property of JS1ider is related to tick marks: the snapToTicks property, set with 
public void setSnapToTicks(boolean newValue). When this property is true and tick marks are 
displayed, after you move the slider's thumb, the thumb will rest only on a tick. Forinstance, if 
a slider has a range of 0-100 with tick marks at every tenth unit, and you drop the thumb at the 
33 mark, the thumb will snap to the position of the tick at 30. Iftick marks aren't displayed, the 
property setting has no effect, including when labels are displayed without tick marks. 


Labeling JSlider Positions 


As Figure 12-5 (shown earlier in the chapter) demonstrates, you can label any position within 
the JSlider with a Component. When a position is labeled, the component will be displayed next 
to it. The labels are stored within a lookup table that subclasses the Dictionary class, where the 
Key is the Integer position and the value is the Component. Any AWT Component can be the label; 
however, the JLabel is best suited to the role. Figure 12-7 shows howthe dictionary for the right 
slider of Figure 12-5 might look. 


new new JLabel (new 
Integer(0) DiamondIcon(Color.RED)) 


nen new JLabel("Ten") 
Integer(10) 


new new JLabel("Twenty-Five") 


a Me 
neY new JLabel("Thirty-Four”) 


— 7 

nen new JLabel("Fifty-Two") 
o > 

nen new JLabel("Seventy") 


Integer(70) 


nen new JLabel("Eighty-Two") 


= pom 
new new JLabel (new 


Integer(100) DiamondIcon(Color.BLACK)) 


Figure 12-7. A JSlider dictionary 
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Normally, the Dictionary used to store the labels is a Hashtable. However, any class that 
extends the Dictionary class and that can use Integer keys will do. After you've created 
your dictionary of labels, you associate the dictionary with the slider with the public void 
setlabelTable(Dictionary newValue) method. The following source creates the label lookup 
table associated with Figure 12-7. 


Hashtable<Integer, JLabel> table = new Hashtable<Integer, JLabel>(); 
table.put (O, new JLabel(new DiamondIcon(Color.RED))); 

table.put (10, new JLabel("Ten")); 

table.put (25, new JLabel("Twenty-Five")); 

table.put (34, new JLabel("Thirty-Four")); 

table.put (52, new JLabel("Fifty-Two")); 

table.put (70, new JLabel("Seventy")); 

table.put (82, new JLabel("Eighty-Two")); 

table.put (100, new JLabel(new DiamondIcon(Color.BLACK))); 
aJSlider.setlabelTable (table); 


Note Keep in mind that with J2SE 5.0, the compiler will auto-box an int parameter into an Integer. 


Simply associating the label table with the slider won't display the labels. To enable their 
painting, you need to call the public void setPaintLabels(boolean newValue) method with a 
parameter of true. Ifyou haven't manually created a table of labels, the system will create one 
with an interval of values reflecting the major tick spacing. For example, the left slider of Figure 
12-5 has a slider range of 0-100 and major tick spacing of 10. When setPaintLabels(true) is 
called on that slider, labels are created for 0, 10, 20, and so on, all the way up to 100. The minor 
tick spacing is irrelevant as far as automatic generation of labels goes. And the ticks don't need 
to be painted for the labels to appear; the getPaintTicks() method can return false. 

The automatic creation of labels is done through the public Hashtable createStandardw» 
Labels(int increment) method, where the incrementis the major tick spacing. You don't need 
to call this method directly. If you want to create the labels from other than the minimum 
value, you can call the overloaded public Hashtable createStandardLabels 
(int increment, int start) variety, and associate the hash table with the slider yourself. 


Customizing a JSlider Look and Feel 


Each installable Swing look and feel provides a different JS1ider appearance and set of default 
UTResource values. Figure 12-8 shows the appearance of the JSlider component for the prein- 
stalled set of look and feel types. 
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Figure 12-8. JSlider under different look and feel types 


Two look-and-feel-related properties are part of the JSlider class definition. By default, 
the minimum slider value for a horizontal slider is at the left; for a vertical slider, it's at the 
bottom. To change the direction of a slider, call the public void setInverted(boolean nenValue) 
method with an argument of true. In addition, the track that the slider moves along is displayed 
by default. You can turn it off with the public void setPaintTrack(boolean newValue) method. 
A value of false turns off the track display. Figure 12-9 identifies the JSlider track and points 
out the minimum and maximum positions of regular and inverted sliders. 


£ Inverted Sliders 


Track 


Inverted 


Figure 12-9. Identifying JSlider positions and tracks 
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Table 12-4 shows the 30 available UIResource-related properties for a JSlider. 


Table 12-4. JSlider UlResource Elements 
Property String 
Slider.actionMap 
Slider.altTrackColor 

Slider .background 
Slider.border 
Slider.darkShadow 
Slider.focus 
Slider.focusGradient 
Slider.focusInputMap 
Slider.focusInputMap.RightToLeft 
Slider.focusInsets 
Slider.foreground 
Slider.gradient 
Slider.highlight 
Slider.horizontalSize 
Slider.horizontalThumbIcon 
Slider.majorTickLength 
Slider.minimumHorizontalSize 
Slider.minimumVerticalSize 
Slider.paintThumbArrowShape 
Slider.paintValue 
Slider.shadow 

Slider.thumb 
Slider.thumbHeight 
Slider.thumbwWidth 
Slider.tickColor 
Slider.trackBorder 
Slider.trackwWidth 
Slider.verticalSize 
Slider.verticalThumbIcon 


SliderUl 


Object Type 
ActionMap 
Color 
Color 
Border 
Color 
Color 
List 
Object[ ] 
InputMap 
Insets 
Color 
List 
Color 
Dimension 
Icon 
Integer 
Dimension 
Dimension 
Boolean 
Boolean 
Color 
Color 
Integer 
Integer 
Color 
Border 
Integer 
Dimension 
Icon 


String 
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The JSlider resources allow customization of elements that aren't accessible through 
JSlider or SliderUI methods. For instance, to customize the JSlider appearance of your 
application, you may want to alter the icon used for the draggable thumb. With just a few lines 
of code, you can take any icon and make it the slider's icon for every slider in your application. 


Icon icon = new Imagelcon("logo.;jpg"); 
UlDefaults defaults = UlManager.getDefaults(); 
defaults.put("Slider.horizontalThumblcon", icon); 


Figure 12-10 shows the results. As with all UlResource properties, this change will affect all 
JSlider components created after setting the property. 


lol 
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Figure 12-10. A JSlider with a custom icon 


Note The height and width of the icon are limited to the dimensions of the slider. Changing the icon property 
doesn't affect the slider size. 


JSlider Client Properties 


By default, with the Metal look and feel, when the tracks visible, the track on which the slider 
moves does not change as the slider is moved over it. Nevertheless, you can enable a client 
property that will signal the slider to fill this track up to the point of the current value that the 
thumb has crossed. The name of this property is JSlider.isFilled, and a Boolean object repre- 
sents the current setting. By default, this setting is Boolean. FALSE. Figure 12-11 demonstrates 
both a Boolean. TRUE and a Boolean. FALSE setting; the code fragment follows: 


JSlider oneJSlider = new JSlider(); 
oneJSlider.putClientProperty("JSlider.isFilled", Boolean.TRUE); 
JSlider anotherJSlider = new JSlider(); 

// Set to default setting 
anotherJSlider.putClientProperty("JSlider.isFilled", Boolean.FALSE); 


Jal 


Figure 12-11. Filled and unfilled JSlider 
This setting works only in the Metal look and feel. The Ocean theme of the Metal look and 


feel ignores this setting, always drawing the track filled. To get this behavior, you need to setthe 
system property swing .metalTheme to steel, asin java -Dswing.metalTheme=steel ClassName. 
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JProgressBar Class 


Swing/s JProgressBar is different from the other BoundedRangeModel components. Its main 
purpose is not to get input from the user, but rather to present output. This output is in the 
form of a process completion percentage. As the percentage increases, a bar progresses across 
the component until the job is completed and the bar is filled. The movement of the bar is 
usually part of some multithreaded task, to avoid affecting the rest of the application. 

Figure 12-12 shows several sample JProgressBar components. The top bar uses all the 
display defaults. The bottom bar adds a border around the component and displays the 
completion percentage. The right bar removes the border, and the left bar has a fixed string 
present instead of a completion percentage. 


> progresstarsrus E 


Reading File 


Figure 12-12. Sample JProgressBar components 


From an object-oriented perspective, there are two primary parts to a JProgressBar: 
The familiar BoundedRangeMode] stores the data model for the component, and the ProgressUuI 
is the user interface delegate. 


Note To display a progress bar in a dialog box, use the ProgressMonitor class discussed in Chapter 9. 


Creating JProgressBar Components 


There are five different constructors for JProgressBar: 


public JProgressBar() 
JProgressBar aJProgressBar = new JProgressBar(); 


public JProgressBar(int orientation) 
// Vertical 

JProgressBar aJProgressBar 
// Horizontal 

JProgressBar bJProgressBar = new JProgressBar(JProgressBar.HORIZONTAL); 


new JProgressBar(JProgressBar.VERTICAL); 


public JProgressBar(int minimum, int maximum) 
JProgressBar aJProgressBar = new JProgressBar(0, 500); 
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public JProgressBar(int orientation, int minimum, int maximum) 
JProgressBar aJProgressBar = new JProgressBar(JProgressBar.VERTICAL, O, 1000); 


public JProgressBar(BoundedRangeModel model) 

// Data model, initial value O, range 0-250, and extent of O 
DefaultBoundedRangeModel model = new DefaultBoundedRangeModel(0, O, O, 250); 
JProgressBar aJProgressBar = new JProgressBar(model); 


Creating a JProgressBar with no arguments results in a horizontal progress bar with a 
default data model. The model has an initial value of 0, a minimum value of 0, a maximum 
value of 100, and an extent of 0. The progress bar has an extent, but it doesn't use it, even 
though it's part of the data model. 

You can explicitly set the orientation with JProgressBar.HORIZONTAL or 
JProgressBar.VERTICAL, as well as any of the specific model properties, with the different 
constructors. In addition, you can explicitly set the data model for the component. 


Caution Initializing the orientation to a value not equivalent to VERTICAL or HORIZONTAL throws an 
I1llegalArgumentException. 


Creating a JProgressBar from a BoundedRangeModel is a little awkward in the sense that the 
progress bar virtually ignores one setting and the initial value is normally initialized to the 
minimum. Assuming you want the JProgressBar to start as a user might expect it to, you need 
to remember to set the extent to 0 and the value to the minimum when creating the model. If 
you increase the extent property, the maximum setting of the value property is decreased by 
that amount, and the value setting will never reach the setting of the maximum property. 


JProgressBar Properties 


After you've created a JProgressBar, you may want to modify it. Table 12-5 shows the 14 properties 
of JProgressBar. 


Table 12-5. JProgressBar Properties 


Property Name Data Type Access 
accessibleContext AccessibleContext Read-only 
borderPainted boolean Read-write bound 
changeListeners ChangeListener[ ] Read-only 
indeterminate boolean Read-write bound 
maximum int Read-write 
minimum int Read-write 

model BoundedRangeModel Read-write 
orientation int Read-write bound 
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Table 12-5. JProgressBar Properties (Continued) 


Property Name Data Type Access 
percentComplete double Read-only 

string String Read-write bound 
stringPainted boolean Read-write bound 
UI ProgressBarUl Read-write 
UlClassID String Read-only 

value int Read-write 


Painting JProgressBar Borders 


All JComponent subclasses feature a border property by default, and the JProgressBar has a 
special borderPainted property to easily enable or disable the painting of the border. Calling 
thepublic void setBorderPainted(boolean newValue) method with a parameter of false turns 
off the painting of the progress bar's border. The right-hand progress bar in Figure 12-12 
(shown earlier) has its border turned off. The source for its initialization follows: 


JProgressBar cJProgressBar = new JProgressBar(JProgressBar.VERTICAL); 
cJProgressBar.setBorderPainted(false); 


Labeling a JProgressBar 


The JProgressBar supports the display of text within the center of the component. There are 
three forms of this labeling: 


+ By default, no label exists. 


+ Todisplaythe percentage completed [100 x (value-minimum) / (maximum-—minimum)], 
call the public void setStringPainted(boolean newValue) method with a parameter of 
true. This will resultin a range from 0% to 100% displayed. 


+ To change the label to a fixed string, call the public void setString(String newValue) 
method and setStringPainted(true). On a vertical progress bar, the string is drawn 
rotated, so a longer string will fit better. 


The left and bottom progress bars in Figure 12-12 demonstrate the fixed label and 
percentage label, respectively. The source code to create both progress bars follows: 


JProgressBar bJProgressBar = new JProgressBar(); 
bJProgressBar.setStringPainted(true); 

Border border = BorderFactory.createTitledBorder("Reading File"); 
bJProgressBar.setBorder(border); 


JProgressBar dJProgressBar = new JProgressBar(JProgressBar.VERTICAL); 
dJProgressBar.setString("Ack"); 
dJProgressBar.setStringPainted(true); 
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Using an Indeterminate JProgressBar 


Some tasks don't have a fixed number of steps, or they do have a fixed number of steps, but you 
don't know what that number is until after all the steps are done. For this type of operation, the 
JProgressBar offers an indeterminate mode where the bar within the JProgressBar bounces 
back and forth from side to side, or top to bottom, depending on the direction of the progress 
bar. To enable this mode, just call the public void setIndeterminate(boolean newValue) 
method with a value of true. Figure 12-13 shows what an indeterminate progress bar looks like 
at different times. The length of the sliding box is one-sixth the available space and seems to 
not be settable. 


l0lx l0lx 


Figure 12-13. Sample indeterminate JProgressBar 


Stepping Along a JProgressBar 


The main usage of the JProgressBar is to show progress as you step through a series of operations. 
Normally, you set the minimum value of the progress bar to zero and the maximum value to 
the number of steps to perform. Starting with a value property of zero, you increase the value 
to the maximum as you perform each step. All these operations imply multithreading, which is, 
in fact, absolutely necessary. In addition, when updating the progress bar's value, you need 
to remember to update it only from within the event dispatching thread (with the help of 
EventQueue.invokeAndWait (), if appropriate, as described in Chapter 2). 

The process of having a progress bar step through its range is as follows: 


1. Initialize it. This is the basic process of creating a JProgressBar with the desired orien- 
tation and range. In addition, perform any bordering and labeling here. 


JProgressBar aJProgressBar = new JProgressBar(0, 50); 
aJProgressBar.setStringPainted(true); 


2. Start up the thread to perform the desired steps. Probably as the result of performing 
some action on the screen, you'll need to start the thread to do the work the progress 
bar is reporting. You need to start a new thread so that the user interface remains 
responsive. 


Thread stepper = new BarThread (aJProgressBar); 
stepper.start(); 


3. Perform the steps. Ignore updating the progress bar, and instead write the appropriate 
code to perform each step. 


static class BarThread extends Thread ( 
private static int DELAY = 500; 
JProgressBar progressBar; 
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public BarThread (JProgressBar bar) ( 
progressBar = bar; 


J 


public void run() £ 
int minimum = progressBar.getMinimum(); 
int maximum = progressBar.getMaximum(); 
for (int i=minimum; i<maximum; d++) ( 
try ( 
// Our job for each step is to just sleep 
Thread. sleep(DELAY); 
) catch (InterruptedException ignoredException) ( 
) catch (InvocationTargetException ignoredException) ( 
// The EventQueue.invokeAndWait() call 
// we'11 add will throw this 
J 
y 
J 
y 


4. For each step, have the thread update the progress bar in the event thread. Create the 
Runnable class just once outside the for loop. Itisn't necessary to create one for each step. 


Runnable runner = new Runnable() £ 
public void run() £ 
int value = progressBar.getValue(); 
progressBar.setValue(value+1); 
) 
E 


Within the loop, tell the runner to update the progress bar. This update must be done in 
the event thread using the special Event0ueue method invokeLater() or invokeAndWait (>), 
because you're updating a property of the JProgressBar. 


EventQueue.invokeAndWait (runner); 


The complete working example is shown in Listing 12-5. 


Listing 12-5. JProgressBar Sample 


import javax.swing.*; 

import java.awt.*; 

import java.awt.event.*; 

import java.lang.reflect.InvocationTargetException; 


public class ProgressBarStep ( 
static class BarThread extends Thread ( 
private static int DELAY = 500; 
JProgressBar progressBar; 
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public BarThread(JProgressBar bar) ( 
progressBar = bar; 


J 


public void run() £ 
int minimum = progressBar.getMinimum(); 
int maximum = progressBar.getMaximum(); 
Runnable runner = new Runnable() 4 
public void run() £ 
int value = progressBar.getValue(); 
progressBar.setValue(value+1); 
J 
5 
for (int i=minimum; i<maximum; i++) ( 
try ( 
EventQueue.invokeAndWait (runner); 
// Our job for each step is to just sleep 
Thread. sleep(DELAY); 
) catch (InterruptedException ignoredException) ( 
) catch (InvocationTargetException ignoredException) ( 
y 
J 
J 


) 
public static void main(String args[]) ( 


Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("Stepping Progress"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
final JProgressBar aJProgressBar = new JProgressBar(0, 50); 
aJProgressBar.setStringPainted(true); 


final JButton aJButton = new JButton("Start"); 


ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent e) ( 
aJButton.setEnabled(false); 
Thread stepper = new BarThread(aJProgressBar); 
stepper.start(); 
) 
5 
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aJButton.addActionListener(actionListener); 
frame.add(aJProgressBar, BorderLayout.NORTH); 
frame.add(aJButton, BorderLayout .SOUTH); 
frame.setSize(300, 200); 
frame.setVisible(true); 
y 
5 
EventQueue.invokelLater(runner); 
) 
) 


Figure 12-14 shows the demonstration program after selecting the button and at 22% 
completion. 


22% 


ALE 


Figure 12-14, JProgressBar in action 


By simply changing the sleep action in Listing 12-5 to the desired operation, this example 
should provide a suitable framework for reuse. 


Note To have the progress bar fill in the opposite direction, have the value start at the maximum and 
decrease it with each step. You probably don't want to display the percentage-completed string, as it will start 
at 100% and decrease to 0%. 


Handling JProgressBar Events 


Technically, the JProgressBar class supports notification of data model changes through a 
ChangeListener. In addition, you can attach a ChangeListener to its data model. Because the 
progress bar is meant more for visualization of output than for providing input, you typically 
won'tuse a ChangelListener with it. However, there may be times when this is appropriate. 

To reuse the BoundedChangeListener from Listing 12-3 earlier in this chapter, make one final 
change (as shown in boldface in Listing 12-6), because the source of these change events is the 
JProgressBar. 
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Listing 12-6. ChangeListener for BoundedRangeModel, JSlider, and JProgressBar 


import javax.swing.*; 
import javax.swing.event.*; 


public class BoundedChangeListener implements ChangeListener ( 
public void stateChanged(ChangeEvent changeEvent) £ 

Object source = changeEvent.getSource(); 

if (source instanceof BoundedRangeModel) ( 
BoundedRangeModel aModel = (BoundedRangeModel) source; 
if (laModel.getValuelsAdjusting()) ( 

System.out.println ("Changed: " + aModel.getValue()); 

) 

) else if (source instanceof Jslider) ( 
JSlider theJSlider = (JSlider)source; 
if (ItheJSlider.getValuelsAdjusting()) ( 

System.out.println ("Slider changed: " + theJSlider.getValue()); 

) 

) else if (source instanceof JProgressBar) ( 
JProgressBar theJProgressBar = (JProgressBar)source; 
System.out.println ("ProgressBar changed: " + theJProgressBar.getValue()); 

y else [ 
System.out.println ("Something changed: 

) 

J 
) 


" 


+ source); 


Customizing a JProgressBar Look and Feel 


Each installable Swing look and feel provides a different JProgressBar appearance and set of 
default UTResource values. Figure 12-15 shows the appearance ofthe JProgressBar component 
for the preinstalled set of look and feel types. 

Table 12-6 shows the set of available UIResource-related properties for a JProgressBar. 
It has 15 different properties. 


Table 12-6. JProgressBar UlResource Elements 


Property String Object Type 
ProgressBar.background Color 
ProgressBar.border Border 
ProgressBar.celllLength Integer 
ProgressBar.cellSpacing Integer 
ProgressBar.cycleTime Integer 
ProgressBar. font Font 


ProgressBar.foreground Color 
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Table 12-6. JProgressBar UlResource Elements (Continued) 


Property String Object Type 
ProgressBar.highlight Color 
ProgressBar.horizontalSize Dimension 
ProgressBar.repaintInterval Integer 
ProgressBar.selectionBackground Color 
ProgressBar.selectionForeground Color 
ProgressBar.shadow Color 
ProgressBar.verticalSize Dimension 
ProgressBarul String 
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Figure 12-15. JProgressBar under different look and feel types 


JTextField Class and BoundedRangeModel 
Interface 


The JTextField component is not technically a bounded-range component, but nevertheless, 
it uses BoundedRangeModel. Built inside the JTextField is a scrollable area used when the width 
ofthe component's contents exceedsits visible horizontal space. ABoundedRangeModel controls 
this scrolling area. You'll look at JTextField in more depth in Chapter 15. Here, you can see 


447 


448 CHAPTER 12 BOUNDED RANGE COMPONENTS 


how a JScrollBar can track the scrolling area ofthe JTextField. Figure 12-16 shows the example 
in action, and Listing 12-7 shows the source. 


101 
brihe Emergency Broadcasting System. This is only 
(«E [o] 


Figure 12-16. Tracking a JTextField width with a JScrollBar 


Listing 12-7. JTextField with a JScrollBar for Scrolling 


import javax.swing.*; 

import java.awt.*; 

import java.awt.event.*; 

public class TextSlider extends JPanel ( 

private JTextField textField; 

private JScrollBar scrollBar; 

public TextSlider() f 
setLayout(new BoxLayout(this, BoxLayout.Y_AXIS)); 
textField = new JTextField(); 
scrollBar = new JScrollBar(JScrol1Bar.HORIZONTAL); 
BoundedRangeModel brm = textField.getHorizontalVisibility(); 
scrollBar.setModel (brm); 
add(textField); 
add(scrollBar); 

J 

public JTextField getTextField() ( 

return textField; 


) 
public String getText() ( 
return textField.getText(); 
) 
public void addActionListener(ActionListener 1) ( 
textField.addActionListener(1); 

) 
public void removeActionListener(ActionListener 1) ( 
textField.removeActionListener(1); 

) 
public JScrollBar getScrollBar() ( 
return scrollBar; 


) 
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public static void main(String args[]) ( 
Runnable runner = new Runnable() £ 
public void run() £ 
JFrame frame = new JFrame("Text Slider"); 
frame.setDefaultClose0peration(JFrame.EXIT_ON CLOSE); 
final TextSlider ts = new TextSlider(); 
ts.addActionListener(new ActionListener() ( 
public void actionPerformed(ActionEvent e) ( 
System.out.println("Text: " + ts.getText()); 
) 


y; 
frame.add(ts, BorderLayout.NORTH); 


frame.setSize(300, 100); 
frame.setVisible(true); 
) 
5 
EventQueue.invokeLater(runner); 
) 
J 


Normally, the JTextField has no associated scrollbar. In fact, most look and feel types 
don't offer it as an alternative. However, if this component is something you want to incorporate, 
you can reuse itin your own applications. Plenty of accessor methods should make reuse 
simpler, and you can avoid needing to access the internal pieces directly. 


Summary 


In this chapter, you've learned how to use Swing's JScrollBar, JSlider, and JProgressBar 
components. You saw how each uses the BoundedRangeModel interface to control the internal 
data necessary to operate the component, and how the DefaultBoundedRangeModel class offers 
a default implementation of this data model. 

Now that you know how to use the various bounded range components, you can move on 
to Chapter 13, which looks at the controls that offer data selection: JList and JComboBox. 
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CHAPTER 13 


List Model Controls 


Chao: 12 explored the bounded range controls that support scrolling and the input or 
display of some bounded range of values. In this chapter, you'll examine two data-selection 
controls that present a list of choices: JList and JComboBox. The primary difference between 
these controls is that the JList component supports multiple selections, whereas the JComboBox 
does not. Also, the JComboBox lets a user provide a choice that isn't among the available options. 


ListModel Interface 


Figure 13-1 shows the two controls you'll be examining in this chapter. 


Chardonnay Y [4 JComboBox 
Chardonnay = 

Sauvignon 

Riesling 

Cabernet 

Zinfandel JList 
Merlot 

Pinot Noir 

Sauvignon Blanc w 


Figure 13-1. Sample JComboBox and JList controls 


The data model shared by the two components is ListModel, which originates with the 
ListModel interface. The AbstractListModel class provides an implementation basis by supporting 
the management and notification of a set of ListDataListener objects. 

In the case ofa JList component, the data model implementation is the DefaultListModel 
class. This class adds an actual data repository, which follows the API of a Vector, for the different 
elements to be displayed within the JList component. 

In the JComboBox component, an extension ofthe ListModel interface called ComboBoxModel 
supports the notion of a selected item within the model. The DefaultComboBoxModel class 
implements the ComboBoxModel interface through yet another interface, the MutableComboBoxModel, 
which supplies supporting methods for adding and removing elements from the model. 
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Note The BasicDirectoryModel class is another ListModel implementation. This implementation is 
used by the file chooser component, JFileChooser, as described in Chapter 9. 


The actual ListModel interface is rather simple. It provides for management ofa 
ListDataListener, and it accesses the size of a particular element of the model. 


public interface ListModel ( 
// Properties 
public int getSize(); 
// Listeners 
public void addListDataListener(ListDataListener 1); 
public void removeListDatalListener(ListDatalistener 1); 
// Other methods 
public Object getElementAt(int index); 


AbstractListModel Class 


The AbstractListModel class provides a partial implementation ofthe ListModel interface. You 
need to provide only the data structure and the data. The class provides for the list management 
of ListDataListener objects and the framework for notification of those listeners when the 
data changes. You can also get the list of listeners by using the public ListDataListener[ ] 
getListDatalisteners() method. When you modify the data model, you must then call the 
appropriate method of AbstractListModel to notify the listening ListDataListener objects: 


+ protected void fireIntervalAdded(Object source, int index0, int index1): To be 
called after adding a contiguous range of values to the list. 


+ protected void fireIntervalRemoved(Object source, int index0, int index1): To be 
called after removing a contiguous range of values from the list. 


+ protected void fireContentsChanged(Object source, int index0, int index1): To be 
called if the modified range wasn't contiguous for insertion, removal, or both. 


Note The ranges specified by the fireXXX() methods of AbstractListModel are closed intervals. This 
simply means that the indices are the endpoints of the range modified. There's no implied order for the 
indices; indexo, for example, doesn't need to be less than index1. The only requirement is that the methods 
be called after the data model has changed. 


If you have your data in an existing data structure, you need to convert it into a form that 
one of the Swing components understands or implement the ListModel interface yourself. As 
you'll see, an array or Vector is directly supported by JList and JComboBox. You can also wrap 
your data structure into an AbstractListModel. For instance, if your initial data structure is an 
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ArrayList from the Collections framework, you can convert the data structure to a ListModel 
with the following code: 


final List arrayList = ...; 
ListModel model = new AbstractListModel() f 
public int getSize() ( 
return arrayList.size(); 
) 
public Object getElementAt(int index) £ 
return arrayList.get(index); 


J 


) 


The other option is to just pass the List into the Vector constructor, and then pass that 
Vector into the JList constructor. Effectively, you've then done the same thing. 


DefaultListModel Class 


The DefaultListModel class provides a data structure for you to store the data internally in the form 
of a Vector. You just need to add the data, because the class manages the ListDataListener list 
for you. 

First, you create the data structure with the no-argument constructor: DefaultListModel 
model = new DefaultListModel(). Then you manipulate it. As shown in Table 13-1, the 
DefaultListModel class has only two properties. 


Table 13-1. DefaultListModel Properties 


Property Name Data Type Access 
empty boolean Read-only 
size int Read -write 


The DefaultListModel class provides all its operational methods through a series of public 
methods. To add elements, use the following methods: 


public void add(int index, Object element) 
public void addElement(Object element) 
public void insertElementAt(Object element, int index) 


The addElement () method ofDefaultListModel adds the element to the end of the data model. 
To change elements, use these methods: 


public Object set(int index, Object element) 
public void setElementAt(Object element, int index) 


And to remove elements, these methods are provided: 
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public void clear() 

public Object remove(int index) 

public void removeAll1Elements() 

public boolean removeElement (Object element) 

public void removeElementAt(int index) 

public void removeRange(int fromIndex, int toIndex) 


The removeElement () method returns a status: true ifit found the object and removed it, 
and false otherwise. 

The DefaultListModel class is useful when you don't have your data in an existing data 
structure. For example, the results ofa database query come back as a JDBC ResultSet. Ifyou 
wish to use those results as the basis for what to display in a JList, you must store them some- 
where. That somewhere can be a DefaultListModel, as demonstrated by the following: 


ResultSet results = aJDBCStatement.executeQuery ( 
"SELECT columnName FROM tableName"); 
DefaultListModel model = new DefaultListModel (>); 
while (results.next()) ( 
model. addElement (result .getString(1)); 
) 


Listening for ListModel Events with a ListDataListener 


If you're interested in finding out when the contents of the list model change, you can register 
a ListDataListener with the model. Three separate methods of the interface tell you when 
contents are added, removed, or altered. Alteringthe data model means adding and/or removing 
contents from one or more regions of the data model or changing the existing contents without 
adding or removing anything. The following is the interface definition: 


public interface ListDatalistener extends EventListener f 
public void contentsChanged(ListDataEvent e); 
public void intervalAdded(ListDataEvent e); 
public void intervalRemoved(ListDataEvent e); 


J 


Upon notification of the list-altering event, you're passed a ListDataEvent instance, which 
contains three properties, as shown in Table 13-2. 


Table 13-2. ListDataEvent Properties 


Property Name Data Type Access 
index0 int Read-only 
index1 int Read-only 


type int Read-only 
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The indices aren't necessarily ordered, and neither are the bounds ofthe altered region. In 
the case of the list model contents changing, not everything within the region may have been 
altered. The area whose contents did change is the bounded region specified by the indices. 
The type property settingis one ofthree constants, as shown in Table 13-3, that map directly to 
the specific interface method called. 


Table 13-3. ListDataEvent Type Constants 


Type Constant Method 

CONTENTS CHANGED contentsChanged() 
INTERVAL_ADDED intervalAdded() 
INTERVAL_REMOVED intervalRemoved() 


If any ListDataListener objects are attached to the data model when any one of the oper- 
ational methods of the DefaultListModel class are called, each of the listeners will be notified 
of the data model change. To demonstrate the use of ListDataListener and the dynamic 
updating of the data model, the ModifyModelSample program shown in Listing 13-1 uses all the 
DefaultListModel class modifying methods, sending the output in the form of the event and 
list contents to a JTextArea. 


Listing 13-1. Modifying the Data Model 


import javax.swing.*; 

import javax.swing.event.*; 
import java.awt.*; 

import java.awt.event.*; 
import java.io.*; 

import java.util.Enumeration; 


public class ModifyModelSample ( 
static String labels[] = (["Chardonnay", "Sauvignon", "Riesling", "Cabernet", 
"Zinfandel”, "Merlot", "Pinot Noir", "Sauvignon Blanc", "Syrah", 
"Gewirztraminer"); 


public static void main(String args[]) ( 
Runnable runner = new Runnable() £ 
public void run() £ 
JFrame frame = new JFrame("Modifying Model"); 
frame.setDefaultClose0peration(JFrame.EXIT_ON CLOSE); 


// Fill model 

final DefaultListModel model = new DefaultListModel/(); 

for (int i=0, n=labels.length; i<n; i++) ( 
model.addElement(labels[i]); 

) 


456 CHAPTER 13 LIST MODEL CONTROLS 


Jlist jlist = new JList(model); 
JScrollPane scrollPane1 = new JScrollPane(jlist); 
frame.add(scrollPane1, BorderLayout.WEST); 


final JTextArea textArea = new JTextArea(); 
textArea.setEditable(false); 

JScrollPane scrollPane2 = new JScrollPane(textArea); 
frame.add(scrollPane2, BorderLayout.CENTER); 


ListDatalistener listDataListener = new ListDataListener() ( 
public void contentsChanged(ListDataEvent listDataEvent) ( 
appendEvent(listDataEvent); 
h 
public void intervalAdded(ListDataEvent listDataEvent) ( 
appendEvent (listDataEvent); 
y 
public void intervalRemoved(ListDataEvent listDataEvent) ( 
appendEvent(listDataEvent); 
) 
private void appendEvent(ListDataEvent listDataEvent) ( 
StringWriter sw = new StringWriter(); 
PrintWriter pw = new PrintWriter(sw); 
switch (listDataEvent.getType()) ( 
case ListDataEvent.CONTENTS CHANGED: 
pw.print("Type: Contents Changed"); 
break; 
case ListDataEvent.INTERVAL_ADDED: 
pw.print("Type: Interval Added"); 
break; 
case ListDataEvent.INTERVAL_REMOVED: 
pw.print("Type: Interval Removed"); 
break; 


) 
pw.print(", Index0: " + listDataEvent.getIndex0()); 


pw.print(", Index1: " + listDataEvent.getIndex1()); 
DefaultListModel theModel = 
(DefaultListModel)listDataEvent.getSource(); 
pw.println(theModel); 
textArea.append(sw.toString()); 
h 
5 


model.addListDataListener(listDataListener); 
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// Set up buttons 
JPanel jp = new JPanel(new GridLayout(2, 1)); 
JPanel jp1 = new JPanel(new FlowLayout(FlowLayout.CENTER, 1, 1)); 
JPanel jp2 = new JPanel(new FlowLayout(FlowLayout.CENTER, 1, 1)); 
jp.add(jp1); 
jp.add(jp2); 
JButton jb = new JButton("add F"); 
jp1.add(jb); 
jb.addActionListener(new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
model.add(O, "First"); 
h 
y; 
jb = new JButton("addElement L"); 
jp1.add(jb); 
jb.addActionListener(new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
model .addElement ("Last"); 
h 
y; 
jb = new JButton("insertElementAt M"); 
jp1.add(jb); 
jb.addActionListener(new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
int size = model.getSize(); 
model.insertElementAt("Middle", size/2); 
) 
y; 
jb = new JButton("set F"); 
jp1.add(jb); 
jb.addActionListener(new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
int size = model.getSize(); 
if (size != 0) 
model.set(O, "New First"); 
J 
y; 
jb = new JButton("setElementAt L"); 
jp1.add(jb); 
jb.addActionListener(new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
int size = model.getSize(); 
if (size != 0) 
model.setElementAt("New Last", size-1); 


E 
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jb = new JButton("load 10"); 
jp1.add(jb); 
jb.addActionlListener(new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
for (int i=0, n=labels.length; i<n ;1++) ( 
model .addElement(labels[i]); 
) 
) 
); 
jb = new JButton("clear”); 
jp2.add(jb); 
jb.addActionlListener(new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
model.clear(); 
, 
); 
jb = new JButton("remove F"); 
jp2.add(jb); 
jb.addActionlListener(new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
int size = model.getSize(); 
if (size != 0) 
model .remove(0); 
) 
»; 
jb = new JButton("removeAl11Elements"); 
jp2.add(jb); 
jb.addActionlListener(new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
model .removeA11Elements(); 
! 
y; 
jb = new JButton("removeElement 'Last'"); 
jp2.add(jb); 
jb.addActionlListener(new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
model .removeElement("Last"”); 
) 
»; 
jb = new JButton("removeElementAt M"); 
jp2.add(jb); 
jb.addActionlListener(new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
int size = model.getSize(); 
if (size != 0) 
model. removeElementAt(size/2); 


y; 
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jb = new JButton("removeRange FM"); 
jp2.add(jb); 
jb.addActionListener(new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
int size = model.getSize(); 
if (size != 0) 
model .removeRange(0,size/2); 
) 


»; 
frame.add(jp, BorderLayout. SOUTH); 


frame.setSize(640, 300); 
frame.setVisible(true); 


y; 

EventQueue.invokeLater(runner); 

Figure 13-2 shows the output for one such run, after several buttons were selected. 
lolx 
First > : Interval Added, Index0: O, Index1: O[First, Chardonnay, Sauvignon, Riesling, Cabernet, 14 
Sauvignon Type: Interval Added, Indexú: 11, Index1: 11[First, Chardonnay, Sauvignon, Riesling, Cabern 
Riesling Type: Contents Changed, Index0: 0, Index1: O[New First, Chardonnay, Sauvignon, Riesling, 
Cabernet Type: Contents Changed, Index0: 0, Index1: O[New First, Chardonnay, Sauvignon, Riesling, 
Zinfandel Type: Contents Changed, Index0: 11, Index1: 11[New First, Chardonnay, Sauvignon, Rieslin 

!" anta Type: Contents Changed, Index0: 0, Index1: O[New First, Chardonnay, Sauvignon, Riesling, 
Middle Type: Interval Added, Index0: 6, Index1: 6[New First, Chardonnay, Sauvignon, Riesling, Cabe 
Merlot Type: Interval Rernoved, Index0: O, Index: 12[] 

Pinot Noir Type: Interval Added, Index0: 0, Index1: O[Chardonnay] 
Sauvignon Blanc| [Type: Interval Added, Index: 1, Index1: 1[Chardonnay, Sauvignon] 
Syrah Type: Interval Added, Index0: 2, Index1: 2[Chardonnay, Sauvignon, Riesling] 

New Last Type: Interval Added, Index0: 3, Index1: 3[Chardonnay, Sauvignon, Riesling, Cabernet] ml 
Chardonnay |w|4 1 [»] 
add F addElement L insertElementAt M set F setElementAt L load 10 
clear remove F removeAllElements removeElement 'Last' removeElementát M 


Figure 13-2. A listing for data model changes 


Note To help you decode the button labels in Figure 13-2, an Fmeans the method affects the first cell, an 
M means it affects the middle cell, and an £ means it affects the last cell. The removeElement “Last” button 
will remove the first element in the data model whose content is Last. 


The retrieving methods ofthe DefaultListModel class are quite varied in their capabilities. 
The class has the basic accessor methods public Object get(int index), public Object 
getElementAt(int index), and public Object elementAt(int index), which all do the same 
thing. The DefaultListModel class also has more specific methods. For instance, to work with 
all elements, you can obtain an instance of Enumeration using public Enumeration elements(). 
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Or, if you want to work with all elements as an array, use either public Object[] toArray() or 
public void copyInto(Object anArray[]). You can also check for the existence of an element 
within a model with methods such as public boolean contains(Object element), public int 
index0f (Object element), public int index0f(Object element, int index), public int 
lastIndex0f (Object element), and public int lastIndex0f(Object element, int index). 


Tip Once you're finished adding elements to the data model, it's a good idea to trimits length with public void 
trimToSize(). This removes any extra preallocated space within the internal data structure. In addition, if you 
know the size ofthe data model in advance, you can call public void ensureCapacity(int minCapacity) to 
preallocate space. Both of these methods work only with DefaultListModel. 


ComboBoxModel Interface 


The ComboBoxModel interface extends the ListModel interface. The key reason for this extension 
is that the classes that implement the ComboBoxModel interface need to manage the selected 
item internally through a selectedItem property, as shown by the interface definition. 


public interface ComboBoxModel extends ListModel ( 
// Properties 
public Object getSelectedItem(); 
public void setSelectedItem(Object anltem); 

J 


MutableComboBoxModel Interface 


In addition to the ComboBoxModel interface, another data model interface, 
MutableComboBoxModel, extends ComboBoxModel to make methods available to modify the 
data model. 


public interface MutableComboBoxModel extends ComboBoxModel £ 
// Other methods 
public void addElement(Object obj); 
public void insertElementAt(Object obj, int index); 
public void removeElement (Object obj); 
public void removeElementAt(int index); 


The JComboBox component uses an implementation of this interface by default. 


DefaultComboBoxModel Class 


The DefaultComboBoxModel class extends the AbstractListModel class to provide an appropriate 
data model for the JComboBox. Because of this extension, it inherits the managing of the 
ListDataListener list. 
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Like DefaultListModel, DefaultComboBoxModel adds the necessary data structure for you to 
collect elements to show within a component. Also, because the model is modifiable, imple- 
menting MutableComboBoxModel causes the data model to call the various fileXXX() methods of 
the AbstractListModel class when the data elements within the model change. 


Note If you create a DefaultComboBoxModel from an array, the elements of the array are copied into an 
internal data structure. If you use a Vector, they're not copied; instead, the actual Vector is used internally. 


To use the data model, you must first create the model with one of the three constructors: 


public DefaultComboBoxModel() 
DefaultComboBoxModel model = new DefaultComboBoxModel (>); 


public DefaultComboBoxModel (Object listData[]) 

String labels[] = £ "Chardonnay", "Sauvignon", "Riesling", "Cabernet", "Zinfandel", 
"Merlot", "Pinot Noir", "Sauvignon Blanc", "Syrah", "Gewiúrztraminer"); 

DefaultComboBoxModel model = new DefaultComboBoxModel (labels); 


public DefaultComboBoxModel (Vector listData) 
Vector vector = aBufferedImage.getSources(); 
DefaultComboBoxModel model = new DefaultComboBoxModel (vector); 


Next, you manipulate the model. Two new properties are introduced in the 
DefaultComboBoxModel class, as shown in Table 13-4. 


Table 13-4. DefaultComboBoxModel Properties 


Property Name Data Type Access 
selectedItem Object Read-write 
size int Read-only 


The data model modification methods for the DefaultComboBoxModel are different from 
those for DefaultListModel. They all come from the MutableComboBoxModel interface: 


public void addElement(Object element) 

public void insertElementAt(Object element, int index) 
public boolean removeElement (Object element) 

public void removeElementAt (int index) 


Due to the flexibility (and functionality) ofthe DefaultComboBoxModel, it's usually 
unnecessary to create your own ComboBoxModel implementation. Just create an instance 
of DefaultComboBoxModel, and then simply fill it from the appropriate data source. 
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Note One case in which you may wish to provide your own model is when you need to support the presence of 
the same item within the model multiple times. With the DefaultComboBoxModel, if you have two items in 
the list whose equals () methods will return true, the model won't work properly. 


If you really want to define your own model implementation, perhaps because you already 
have the data in your own data structure, it works best to subclass the AbstractListModel and 
implement the ComboBoxModel or MutableComboBoxModel interface methods. When subclassing 
the AbstractListModel, you merely need to provide the data structure and the access into it. 
Because the “selected item” part of the data model is maintained outside the primary data 
structure, you need a place to store that, as well. The program source in Listing 13-2 demonstrates 
one such implementation using an ArrayList as the data structure. The program includes a 
main() method to demonstrate the use of the model within a JComboBox. 


Listing 13-2. Using a Custom Data Model 


import java.awt.*; 

import javax.swing.*; 
import java.util.Collection; 
import java.util.ArrayList; 


public class ArrayListComboBoxModel 
extends AbstractListModel implements ComboBoxModel ( 
private Object selectedItem; 
private ArrayList anArrayList; 
public ArrayListComboBoxModel (ArrayList arrayList) ( 
anArraylList = arrayList; 
J 
public Object getSelectedItem() ( 
return selectedlItem; 
J 
public void setSelectedItem(Object nenValue) ( 
selectedItem = newValue; 
J 
public int getSize() ( 
return anArrayList.size(); 
J 
public Object getElementAt(int i) ( 
return anArrayList.get(i); 


J 


public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("ArrayListComboBoxModel"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
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Collection<0bject> col = System.getProperties().values(); 
ArrayList<0bject> arrayList = new ArrayList<0bject>(col); 
ArrayListComboBoxModel model = new ArrayListComboBoxModel (arrayList); 


JComboBox comboBox = new JComboBox (model); 


frame. add(comboBox, BorderLayout .NORTH); 
frame.setSize(300, 225); 
frame.setVisible(true); 
A 
E 
EventQueue.invokeLater(runner); 
) 
J 


Figure 13-3 shows the model in action using the current system properties as the source 
for the data model elements. 


> aroyustcombotomada AE 


¡Java(TM) 2 Runtime Environment, Standard Editi: 
[C:1JDK1.5.0yreibin 

1.5.0-64 

¡Sun Microsystems Inc. 


Ittp:/fava.sun.com!/ 


¡Java HotSpot(TM) Client YM 
¡sun.jo 


Figure 13-3. Using an ArrayListComboBoxModel 


JList Class 


The JList componentis the basic Swing component for selecting one or more items from a set 
of choices. You present the list of choices to the user, and the user can pick one or several, 
depending on the selection mode of the component. 

Three key elements and their implementations define the JList structure: 


+ A data model for holding the JList data, as defined by the ListModel interface 


+ Acell renderer for drawing the elements ofthe JList, as described by the 
ListCellRenderer interface 


+ Aselection model for selecting elements ofthe JList, as described by the 
ListSelectionModel interface 


Creating JList Components 


The JList component has four constructors, which allow you to create a JList instance based 
on your initial data structure: 
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public JList() 
Jlist jlist = new JList(); 


public JList(Object listData[]) 

String labels[] = £ "Chardonnay", "Sauvignon", "Riesling", "Cabernet", "Zinfandel”, 
"Merlot", "Pinot Noir", "Sauvignon Blanc", "Syrah", "Gewúrztraminer"); 

Jlist jlist = new JlList(labels); 


public JList(Vector listData) 
Vector vector = aBufferedImage.getSources(); 
Jlist jlist = new JList(vector); 


public JList(ListModel model) 
ResultSet results = aJDBCStatement.executeQuery ("SELECT colName FROM tableName"); 
DefaultListModel model = new DefaultListModel (>); 
while (result.next()) 
model. addElement (result .getString(1)); 
Jlist jlist = new JList(model); 


If you use the no-argument constructor, you can fill in the data later. However, if you use 
the array or Vector constructor, you can't alter the contents without changing the whole 
model. 


Note If you want to display something other than the toString() results of each array element, see the 
section “Rendering JList Elements” later in this chapter for details on how to do that. 


JList Properties 


After creating a JList component, you can modify each of its many properties. Table 13-5 
shows the 32 properties of JList. 


Table 13-5. JList Properties 


Property Name Data Type Access 
accessibleContext AccessibleContext Read-only 
anchorSelectionIndex int Read-only 
cellRenderer ListCellRenderer Read-write bound 
dragEnabled boolean Read-write 
firstVisiblelndex int Read-only 
fixedCellHeight int Read-write bound 
fixedCellWidth int Read-write bound 


Table 13-5, JList Properties (Continued) 


Property Name 
lastVisiblelndex 


layoutOrientation 
leadSelectionIndex 

listData 
listSelectionListeners 
maxSelectionIndex 
minSelectionIndex 

model 
preferredScrollableViemportSize 
prototypeCellValue 
scrollableTracksViemportHeight 
scrollableTracksViewportWidth 
selectedIndex 

selectedIndices 

selectedValue 

selectedValues 
selectionBackground 
selectionEmpty 
selectionForeground 


selectionMode 


selectionModel 
UI 

UlClassID 
valuelsAdjusting 


visibleRowCount 
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Data Type 
int 
int 
int 


Vector 


ListSelectionListener[ ] 


int 

int 
ListModel 
Dimension 
Object 
boolean 
boolean 
int 

int[ ] 
Object 
Object[ ] 
Color 
boolean 
Color 

int 
ListSelectionModel 
Listul 
String 
boolean 


int 
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Access 
Read-only 


Read-write bound 
Read-only 
Write-only 
Read-only 
Read-only 
Read-only 
Read-write bound 
Read-only 
Read-write bound 
Read-only 
Read-only 
Read-write 
Read-write 
Read-only 
Read-only 
Read-write bound 
Read-only 
Read-write bound 
Read-write 
Read-write bound 
Read-write 
Read-only 
Read-write 


Read-write bound 


Many of the JList properties are related to the process of selection. For instance, 
anchorSelectionIndex, leadSelectionIndex, maxSelectionIndex, minselectionIndex 
selectedIndex, and selectedIndices deal with the indices of the selected rows, while 
selectedValue and selectedValues relate to the contents of the selected elements. 

The anchorSelectionIndex is the most recent index0 of a ListDataEvent, whereas the 
leadSelectionIndex is the most recent index1. 
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To control the preferred number of visible rows shown, set the visibleRowCount property 
of JList. The default setting for this property is 8. 


Scrolling JList Components 


When you're working with a JList component, you must place the component within a 
JScrollPane if you want to allow the user to pick from all available choices. Ifit's not placed 
within a JScrollPane and the default number of rows displayed is smaller than the size of the 
data model, orifthere isn't sufficient space to display the rows, the other choices aren't shown. 
When placed within a JScrol1Pane, the JList offers a vertical scrollbar to move through all the 
available choices. 

Ifyou don't place a JListina JScrollPane and the number of choices exceeds the available 
space, only the top group of choices will be visible, as you can see in Figure 13-4. 


£ Example JList =(0/x/ 
LS E | 
Chardonn: - E) 
: E Sauvignon E 
Sauvignon a 
E Riesling 
Riesling 
Cabernet 
Cabernet ; 
A ¡Zinfandel 
Zinfandel Merlot ¡Y 
Merlot - ' 
y E Pinot Noir 
Pinot Noir ñ 
> ¡Sauvignon Blanc 
Sauvignon Blanc 
Syrah pa 
o e [Gewlirztraminer | + 
Comiirztraminor A 


Figure 13-4. A ten-element JList, in and out of a JScrollPane 


Tip Whenever you see that a class implements the Scro11able interface, it should serve as a reminder 
to place that component within a JScro11Pane before adding it to the application. 


The JScrol1Pane relies on the dimensions provided by the preferredScrollable w» 
ViewportSize property setting to determine the preferred size of the pane contents. When the 
data model of a JList is empty, a default size of 16 pixels high by 256 pixels wide per visible row 
is used. Otherwise, the width is determined by looping through all the cells to find the widest 
one, and the height is determined by the height of the first cell. 

To speed the sizing of the viewport for the JScrol1Pane, you can define a prototype cell by 
setting the prototypeCellValue property. You must be sure the prototype toString() value is 
sufficiently wide and tall to accommodate all the contents of the JList. Then the JScrollPane 
bases the sizing of its viewport on the prototype, and it won't be necessary for the JList to ask 
each cell for its size; instead, it will ask only for the prototype. 

You can also improve performance by assigning a size to the fixedCellHeight and 
tixedCellWidth properties. Setting these properties is another way to avoid having the JList 
ask each cell for its rendered size. Setting both properties is the fastest way to have a JList sized 
within a viewport. Of course, this is also the least flexible because it ensures that the JList 
choices aren't widened (or shortened) when the contents change. However, if you have a large 
number of entries in the data model, this loss of flexibility may be worthwhile to improve 
performance. Figure 13-5 helps you to visualize some of the sizing capabilities ofa JList. 
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Figure 13-5. Sizing entries within a JList 


The source used to generate the output in Figure 13-5 follows in Listing 13-3. The center 
list in the figure contains more than 1,000 fixed-size cells. The top list shows that you can set 
the number of visible rows with setVisibleRowCount (). Notice that the bottom list in the figure 
also uses setVisibleRowCount (). However, because the listisn'tin a JScroll1Pane, the request to 
limit the number of rows is ignored. 


Listing 13-3. Sizing the List Cells 


import javax.swing.*; 

import java.awt.*; 

public class SizingSamples ( 

public static void main(String args[]) ( 
Runnable runner = new Runnable() £ 
public void run() £ 
String labels[] = ("Chardonnay", "Sauvignon", "Riesling", "Cabernet", 

"Zinfandel", "Merlot", "Pinot Noir", "Sauvignon Blanc", "Syrah", 
"Gewirztraminer”); 


JFrame frame = new JFrame("Sizing Samples"); 
frame.setDefaultClose0peration(JFrame.EXIT_ON CLOSE); 


Jlist jlist1 = new JList(labels); 
jlist1.setVisibleRowCount(4); 
DefaultListModel model = new DefaultListModel(); 
model .ensureCapacity(1000); 
for (int i=0;i<100;1++) ( 

for (int j=0;j<10;j++) ( 

model. addElement (labels[3]); 

J 

y 
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JScrollPane scrollPane1 = new JScrollPane(jlist1); 
frame.add(scrollPane1, BorderLayout.NORTH); 


Jlist jlist2 = new JList(model); 
jlist2.setVisibleRowCount(4); 
jlist2.setFixedCellHeight(12); 
jlist2.setFixedCellWidth(200); 

JScrollPane scrollPane2 = new JScrollPane(jlist2); 
frame.add(scrollPane2, BorderLayout.CENTER); 


Jlist jlist3 = new JList(labels); 
jlist3.setVisibleRowCount(4); 
frame.add(jlist3, BorderlLayout. SOUTH); 


frame.setSize(300, 350); 
frame.setVisible(true); 
j 
E 
EventQueue.invokeLater(runner); 
y 
Í 


In addition to placing a JList within a JScroll1Pane, you can also find out which choices 
are visible or request that a specific element be made visible. The firstVisibleIndex and 
lastVisibleIndex properties allow you to find out which choices are currently visible within 
the JScrollPane. Both methods return -1 if nothing is visible; this usually happens where the 
data model is empty. To request that a specific element be made visible, use the public void 
ensurelIndexIsVisible(int index) method. For instance, to programmatically move the list to 
the top, use the following: 


jlist.ensureIndexIsVisible(0); 


Rendering JList Elements 


Every element within the JList is called a cell. Every JList has an installed cell renderer that draws 
every cell when the list needs to be drawn. The default renderer, DefaultListCellRenderer, isa 
subclass of JLabel, which means you can use either text or an icon as the graphical depiction 
for the cell. This tends to suit most users' needs, but sometimes the cell's appearance can 
benefit from some customization. And, because every JList can have at most one renderer 
installed, customization requires that you replace the existing renderer. 


ListCellRenderer Interface and DefaultListCellRenderer Class 


The JList has an installed renderer. A class that implements the ListCellRenderer interface 
provides this renderer. 


public interface ListCellRenderer ( 
public Component getListCellRendererComponent(JList list, Object value, 
int index, boolean isSelected, boolean cellHasFocus); 


CHAPTER 13 LIST MODEL CONTROLS 


When it's time to draw each cell, the interface's sole method is called. The returned 
renderer provides the specific rendering for that one cell of the JList. The JList uses the 
rendering to draw the element, and then gets the next renderer. 

A reference to the enclosing JList is provided to the getListCellRendererComponent () 
method so that the renderer can share display characteristics. The value of the selection 
contains the object in the list's data model at position index. The index is zero-based from the 
beginning ofthe data model. The last two parameters allow you to customize the cell's appear- 
ance based on the cell's state—that is, whether it's selected or has the input focus. 

Listing 13-4 shows a renderer that demonstrates this technique. The sole difference for 
this renderer is that the cell with the input focus has a titled border. After the renderer is 
created, you install it by setting the cellRenderer property of the JList. 


Tip For performance reasons, it is best not to create the actual renderer in the 
getListCellRendererComponent () method. Either subclass Component and return this or 
create a class variable to hold one instance of a Component, which then may be customized and returned. 


Listing 13-4. Rendering the List Cells 


import java.awt.*; 
import javax.swing.*; 
import javax.swing.border.*; 
public class FocusedTitleListCellRenderer implements ListCellRenderer ( 
protected static Border noFocusBorder = 
new EmptyBorder(15, 1, 1, 1); 
protected static TitledBorder focusBorder = 
new TitledBorder(LineBorder.createGraylLineBorder(), "Focused”); 
protected DefaultListCellRenderer defaultRenderer = new DefaultListCellRenderer(); 


public String getTitle() ( 
return focusBorder.getTitle(); 

) 

public void setTitle(String newValue) £ 
focusBorder.setTitle(newValue); 


J 


public Component getListCellRendererComponent(JList list, Object value, 
int index, boolean isSelected, boolean cellHasFocus) f 
JLabel renderer = (JLabel)defaultRenderer.getListCellRendererComponent ( 
list, value, index, isSelected, cellHasFocus); 
renderer.setBorder(cellHasFocus ? focusBorder : noFocusBorder)'; 
return renderer; 
) 
) 
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Caution A common mistake when creating your own renderer is forgetting to make the renderer compo- 
nent opaque. This causes the background coloration of the renderer to be ignored and the list container's 
background to bleed through. With the DefaultListCellRenderer class, the renderer component is 
already opaque. 


A sample program that uses the new renderer follows in Listing 13-5. It doesn't do anything 
special other than install the custom cell renderer that was just created. 


Listing 13-5. Rendering List Cells Sample 


import javax.swing.*; 
import java.awt.*; 
public class CustomBorderSample ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() £ 
String labels[] = ("Chardonnay", "Sauvignon", "Riesling", "Cabernet", 
"Zinfandel”, "Merlot", "Pinot Noir", "Sauvignon Blanc", "Syrah", 
"Gewirztraminer"); 
JFrame frame = new JFrame("Custom Border"); 
frame.setDefaultClose0peration(JFrame.EXIT_ON CLOSE); 
Jlist jlist = new JList(labels); 
ListCellRenderer renderer = new FocusedTitleListCellRenderer(); 
jlist.setCellRenderer(renderer); 
JScrollPane sp = new JScrollPane(jlist); 
frame.add(sp, BorderLayout.CENTER); 
frame.setSize(300, 200); 
frame.setVisible(true); 
y 
E 
EventQueue.invokeLater(runner); 
) 
y 


Figure 13-6 shows the output ofthe sample program. 


E costomtorder A 
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Figure 13-6. A JList with a custom focus border cell renderer 
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Creating a Complex ListCellRenderer 


More often than not, custom cell renderers (like the one shown in Figure 13-6) are necessary 
when the data model consists of more complex data in each element—something not repre- 
sentable by a text string. For instance, Listing 13-6 shows the source for an example where each 
element of the data model consists of a font, foreground color, icon, and text string. Ensuring 
the proper usage of these elements within the renderer simply involves a little more work in 
configuring the renderer component. In this particular example, that data is stored within each 
element of an array in the data model. You could just as easily define a new class or use a 


hash table. 


Listing 13-6. Rendering Complex List Cells 


import java.awt.*; 
import javax.swing.*; 


import javax.swing.border.*; 
public class ComplexCellRenderer implements ListCellRenderer ( 
protected DefaultListCellRenderer defaultRenderer = new DefaultListCellRenderer(); 


public Component getListCellRendererComponent(JList list, Object value, int index, 
boolean isSelected, boolean cellHasFocus) 4 


Font theFont 


= null; 


Color theForeground = null; 


Icon thelcon 
String theText 


Jlabel renderer = 


= null; 
= null; 


(JLabel)defaultRenderer.getListCellRendererComponent ( 


list, value, index, isSelected, cellHasFocus); 


if (value instanceof Object[]) ( 


Object values[] 
theFont 
theForeground 
thelcon 
theText 

) else [ 
theFont Ñ 
theForeground = 
theText 


J 


if (lisselected) ( 


= (Object[ ])value; 

= (Font)values[0]; 

= (Color)values[1]; 
= (Icon)values[2]; 

= (String)values[3]; 


list.getFont(); 
list.getForegrouna(); 


”.., 
, 


renderer.setForeground(theForeground); 


J 


if (thelcon != null) € 
renderer.setIcon(thelcon); 


J 
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renderer.setText(theText); 
renderer.setFont(theFont); 
return renderer; 
) 
Í 


This renderer merely customizes the renderer component returned by the 
DefaultListCellRenderer. The customization is based on the data model value being passed 
in as an array to the value argument of the getListCellRendererComponent() method. 

Listing 13-7 shows the test class. This demonstration program reuses the DiamondIcon 
created in Chapter 4. Most of the code is for initialization of the data model. 


Listing 13-7. Rendering Complex List Cells Sample 


import javax.swing.*; 
import java.awt.*; 
public class ComplexRenderingSample ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 


Object elements[][] = ( 

[new Font("Helvetica", Font.PLAIN, 20), Color.RED, 
new DiamondIcon(Color.BLUE), "Help"), 

[new Font("TimesRoman", Font.BOLD, 14), Color.BLUE, 
new DiamondIcon(Color.GREEN), "Me"?, 

[new Font("Courier", Font.ITALIC, 18), Color.GREEN, 
new DiamondIcon(Color.BLACK), "I'm"P, 

[new Font("Helvetica", Font.BOLD | Font.ITALIC, 12), Color.GRAY, 
new DiamondIcon(Color.MAGENTA), "Trapped"), 

[new Font("TimesRoman", Font.PLAIN, 32), Color.PINK, 
new DiamondIcon(Color.YELLOW), "Inside"?, 

[new Font("Courier", Font.BOLD, 16), Color.YELLOW, 
new DiamondIcon(Color.RED), "This"P, 

[new Font("Helvetica", Font.ITALIC, 8), Color.DARK_GRAY, 
new DiamondIcon(Color.PINK), "Computer") 


Je 


JFrame frame = new JFrame("Complex Renderer"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


Jlist jlist = new JList(elements); 

ListCellRenderer renderer = new ComplexCellRenderer(); 
jlist.setCellRenderer(renderer); 

JScrollPane scrollPane = new JScrollPane(jlist); 
frame.add(scrollPane, BorderLayout.CENTER); 
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// JComboBox comboBox = new JComboBox(elements); 
// comboBox.setRenderer(renderer); 
// frame.add(comboBox, BorderLayout.NORTH); 


frame.setSize(300, 200); 
frame.setVisible(true); 


J 
5 
EventQueue.invokeLater(runner); 
) 
J 
The output of this example is shown in Figure 13-7. 
Jolx 
+ Help 2 
Me 
e 
4 Trapped = 
Inside 


Figure 13-7. Using a more complex list cell renderer 


Tip When you create your own rendering components, you'll find it's best to start with the default list cell 
renderer. This allows you to focus on the specific details you're interested in. Otherwise, you'll need to worry 
about everything, such as the default selection foreground and background colors, and whether you've 
remembered to make the component opaque. Of course, if you want to configure everything yourself, feel free 
to do so. 


Selecting JList Elements 


By default, every JList component is in multiple-selection mode. This means that you can 
select multiple elements within the component. How you select multiple elements depends on 
the user interface you're employing. For instance, with the Ocean look and feel interface, Ctrl- 
select (Ctrl key and left mouse button on a right-handed mouse) acts as a selection toggle, and 
Shift-select acts as a means of range selection. 


ListSelectionModel Interface and DefaultListSelectionModel Class 


An implementation ofthe ListSelectionModel interface controls the selection mechanism for 
a JList component. The interface definition, shown here, defines constants for different selection 
modes and describes how to manage a list of ListSelectionListener objects. It also provides 
the means to describe several selection intervals. 
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public interface ListSelectionModel ( 
// Constants 


public 
public 
public 


public 
public 
public 
public 
public 
public 
public 
public 
public 
public 
public 


public 
public 


public 
public 
public 
public 
public 
public 
public 


final static int MULTIPLE INTERVAL SELECTION; 
final static int SINGLE _INTERVAL_ SELECTION; 
final static int SINGLE SELECTION; 


// Properties 


int getAnchorSelectionIndex(); 

void setAnchorselectionIndex(int index); 
int getLeadSelectionIndex(); 

void setleadSelectionIndex(int index); 
int getMaxSelectionIndex(); 

int getMinSelectionIndex(); 

boolean isSelectionEmpty(); 

int getSelectionMode(); 

void setSelectionMode(int selectionMode); 
boolean getValuelsAdjusting(); 

void setValuelsAdjusting(boolean valuelsAdjusting); 


// Listeners 


void addListSelectionListener(ListSelectionListener x); 
void removeListSelectionListener(ListSelectionListener x); 


// Other methods 


void addSelectionInterval(int index0, int index1); 

void clearselection(); 

void insertIndexInterval(int index, int length, boolean before); 
boolean isSelectedIndex(int index); 

void removeIndexInterval(int index0, int index1); 

void removeSelectionInterval(int index0, int index1); 

void setSelectionInterval(int index0, int index1); 


Three different selection modes are available. Table 13-6 contains the name of each mode 
and its description. 


Table 13-6. ListSelectionModel Modes 


Mode Description 
SINGLE_SELECTION One item at a time can be selected. 
SINGLE_INTERVAL_ SELECTION One contiguous range of items can be selected. 


MULTIPLE _INTERVAL_SELECTION Any set of ranges can be selected. 


Figure 13-8 shows you the results of each selection mode. 
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Figure 13-8. Visual representation of selection modes 


To change the selection mode of a JList, setits selectionMode property to one ofthe 
ListSelectionModel constants shown in Table 13-6. For instance, the following would change 
a list to single-selection mode: 


JList list = new Jlist(...); 
list.setSelectionMode(ListSelectionModel.SINGLE SELECTION); 


The DefaultListSelectionModel class is the default implementation of the 
ListSelectionModel interface. You can examine any of its nine properties, shown in 
Table 13-7, to learn about the currently selected range. 


Table 13-7. DefaultListSelectionModel Properties 


Property Name Data Type Access 

anchorSelectionIndex int Read-write 
leadAnchorNotificationEnabled boolean Read-write 
leadSelectionIndex int Read-write 
listSelectionListeners ListSelectionListener[ ] Read-only 
maxSelectionIndex int Read-only 
minSelectionIndex int Read-only 
selectionEmpty boolean Read-only 
selectionMode int Read-write 
valuelsAdjusting boolean Read-write 


The selection model can show you what is currently being used in the multiple-selection 
mode when the selectionEmpty property is false. Simply ask each index between the minimum 
and maximum selection indices if it's selected with public boolean isSelectedIndex(int index). 
Because multiple-selection mode supports noncontiguous areas, this is the only way to find 
out what's selected. However, the selectedIndices property of JList provides this information 
without you needing to check it manually. 


475 


476 


CHAPTER 13 LIST MODEL CONTROLS 


Listening to JList Events with a ListSelectionListener 


If you want to know when elements of a JList have been selected, you need to 

attach a ListSelectionListener to the JList or the ListSelectionModel. The 
addListSelectionListener() and removeListenerListener() methods of the JList 
only delegate to the underlying ListSelectionModel. When the set of selected elements 
changes, attached listener objects are notified. The interface definition follows: 


public interface ListSelectionListener extends EventListener ( 
public void valueChanged(ListSelectionEvent e); 


J 


The ListSelectionEvent instance received by the listener describes the range of affected 
elements for this selection event, as well as whether or not the selection is still changing, as 
shown in Table 13-8. When a user is still altering selected elements, with a valuelIsAdjusting 
setting of true, you might want to delay performing costly operations such as drawing a high- 
resolution graphics presentation. 


Table 13-8. ListSelectionEvent Properties 


Property Name Data Type Access 

firstIndex int Read-only 
lastIndex int Read-only 
valuelsAdjusting boolean Read-only 


In order to demonstrate selection with a JList, the program shown in Listing 13-8 adds a 
JTextArea to a window to show the output of the selection listener. The listener prints out the 
currently selected items by item position and value. 


Listing 13-8. Rendering Complex List Cells Sample 


import javax.swing.*; 
import javax.swing.event.*; 
import java.awt.*; 

import java.io.*; 


public class SelectingJlListSample ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 

String labels[] = ("Chardonnay", "Sauvignon", "Riesling", "Cabernet", 
"Zinfandel”, "Merlot", "Pinot Noir", "Sauvignon Blanc", "Syrah", 
"Gewirztraminer"); 

JFrame frame = new JFrame("Selecting JList"); 

frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
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Jlist jlist = new JList(labels); 
JScrollPane scrollPane1 = new JScrollPane(jlist); 
frame.add(scrollPane1, BorderLayout.WEST); 


final JTextArea textArea = new JTextArea(); 
textArea.setEditable(false); 

JScrollPane scrollPane2 = new JScrollPane(textArea); 
frame.add(scrollPane2, BorderLayout.CENTER); 


ListSelectionListener listSelectionListener = 
new ListSelectionListener() ( 
public void valueChanged(ListSelectionEvent listSelectionEvent) ( 
StringWriter sw = new StringWriter(); 
PrintWriter pw = new PrintWriter(sw); 
pw.print("First index: " + listSelectionEvent.getFirstIndex()); 
pw.print(", Last index: " + listSelectionEvent.getlastIndex()); 
boolean adjust = listSelectionEvent.getValuelsAdjusting(); 
pw.printin(", Adjusting? " + adjust); 
if (ladjust) ( 
Jlist list = (JList)listSelectionEvent.getSource(); 
int selections[] = list.getSelectedIndices(); 
Object selectionValues[] = list.getSelectedValues(); 
for (int i=0, n=selections.length; i<n; i++) ( 


if (i==0) ( 
pw.print(" Selections: ”); 
J 
pw.print(selections[i] + "/" + selectionValues[i] + " "); 
J 
pw.printlin(); 
y 
textArea.append(sw.toString()); 
J 
y; 


jlist.addListSelectionListener(listSelectionListener); 


frame.setSize(350, 200); 
frame.setVisible(true); 


J 
5 
EventQueue.invokeLater(runner); 


J 
h 


Note If you know that a JList is in single-selection mode, you can get the currently selected ¡tem with 
either the selectedIndex or selectedValue property. 
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Figure 13-9 shows the appearance of the running program. 
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Figure 13-9. Listening for JList selections 


The example in Listing 13-8 prints out only the currently selected items when it is not 
doing a rapid update (when isAdjusting reports false). Otherwise, the program merely 
reports the starting and ending range of selection changes, as well as the adjusting status. The 
example examines the selectedIndices and selectedValues properties of JList to getan ordered 
list of selected items. The selectedIndices and selectedValues arrays are ordered in the same 
way, so a particular element of the data model will show up in the same position in both lists. 

There's no special selection event for double-clicking an item in the list. Ifyou're interested in 
double-click events, you need to fall back to the AWT MouseEvent /MouseListener pair. Adding the 
following code to the program in Listing 13-8 will add appropriate text to the JTextArea for 
double-click events. The key method here is the public int locationToIndex(Point location) 
method of JList, which attempts to map screen coordinates to list elements. 


import java.awt.event.*; 


MouseListener mouseListener = new MouseAdapter() ( 
public void mouseClicked(MouseEvent mouseEvent) ( 
Jlist thelist = (JList)mouseEvent.getSource(); 
if (mouseEvent.getClickCount() == 2) £ 
int index = thelist.locationToIndex(mouseEvent.getPoint()); 
if (index >= 0) [ 
Object o = theList.getModel().getElementAt (index); 
textArea.append("Double-clicked on: " + o.toString()); 
textArea.append(System.getProperty("line.separator")); 
) 
J 
y 
5 


jlist.addMouseListener(mouseListener); 


Note The JList class also provides the public Point indexToLocation(int index) method, which 
produces the reverse behavior, returning a Point as the origin of the provided index. 
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Manually Selecting JList Events 


In addition to detecting when a user selects items in a list, you can also programmatically select 
or deselect items. Ifany ListSelectionListener objects are attached to the JList, they will also 
be notified when the set of selected items is programmatically altered. The following methods 
are available: 


+ Forasingleitem, public void setSelectedValue(Object element, boolean shouldScrol11) 
selects the first item that matches the element. Ifthe element wasn't previously selected, 
everything that was selected will be deselected first. 


+ Forarange ofitems, public void setSelectedInterval(int index0, int index1) 
selects an inclusive range. 


+ Foradding a range of selected items to the already selected set, use public void 
addSelectedInterval(int index0, int index1). 


+ You can clear all the selected items with the public void clearselection() method. 


+ Youcan clear a range of selected items with the public void removeSelectedInterval 
(int index0, int index1) method. 


Displaying Multiple Columns 


Typically, whenever you work with a JList, you present its choices within a single column. 
While this is the usual manner of usage, the Swing JList control offers support for displaying 
its choices within multiple columns. Through the help ofthe setLayoutOrientation() method, 
you can set each JList orientation to lay out cells in columns horizontally or vertically. 
JList.VERTICAL is the default setting where everything appears in one column. 

To lay out cells horizontally, before going to next row, use the value JList.HORIZONTAL_WRAP. 
For example, a list with nine elements would be displayed as shown here: 


0 1 2 
3 4 5 
6 7 8 


To lay out cells vertically, before going to next column, use the value JList.VERTICAL_WRAP. 
For example, a list with nine elements would be displayed as shown here: 


0 3 6 
1 4 7 
2 5 8 


Set the visibleRowCount property of JList to control the number of rows. Otherwise, the 
list width determines the row count for HORIZONTAL_WRAP and the list height for VERTICAL_WRAP. 
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Figure 13-10 shows a sample JList with horizontal wrap, presented as a 3x3 grid. Notice thatit 
still supports multiple-selection mode. 


alolxi 
Zero One Two 
Three Four Five 


Six Seven Eight 


Figure 13-10. A JList with horizontal wrap 


Customizing a JList Look and Feel 


Each installable Swing look and feel provides a different JList appearance and set of default 
UTResource value settings for the component. Figure 13-11 shows the appearance of the JList 
component for the preinstalled set of look and feel types: Motif, Windows, and Ocean. 
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Figure 13-11. JList under different look and feel types 


The available set ofUTResource-related properties for a JList is shown in Table 13-9. For 
the JList component, there are 17 different properties. 


Table 13-9. JList UlResource Elements 


Property String ObjectType 
List.background Color 

List.border Border 
List.cellHeight Integer 
List.cellRenderer ListCellRenderer 
List.focusCellHighlightBorder Border 
List.focusInputMap InputMap 
List.focusInputMap.RightToLeft InputMap 

List.font Font 
List.foreground Color 
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Table 13-9. JList UlResource Elements (Continued) 


Property String Object Type 
List.lockToPositionOnScroll Boolean 
List.rendererUseListColors Boolean 
List.rendererUseUlBorder Boolean 
List.selectionBackground Color 
List.selectionForeground Color 
List.timeFactor Long 
Listul String 


As with most of the UTResource properties, the names of most of the properties are self- 
explanatory. One property, List.timeFactor, requires a bit of extra descriptive text. By default, 
the JList comes with behavior for keyboard selection. As you type, the JList will find the 
entry that matches what you've typed so far. This is done with the help ofthe public int 
getNextMatch(String prefix, int startIndex, Position.Bias bias) method. The “so far” bit 
is controlled by the List.timeFactor setting. As long as the delay between keystrokes doesn't 
exceed the number of milliseconds specified by List.timeFactor (default of 1000), the new key 
pressed is added to the prior keys. Once the factor is exceeded, the search string is reset. 


Creating a Dual List Box 


The example presented in this section creates a new Swing component called a DualListBox. The 
primary purpose of a dual list box is to create two lists of choices: one to pick from and one that 
makes up your result set. This works great when the initial choice listis sizable. Trying to multi- 
select from a JList that contains many selections across multiple screens can be annoying, 
especially if you happen to deselect what you've already selected because you didn't have the 
Shift or Ctrl key held down. With a dual list box, the user selects items in the first list and moves 
them into the second. The user can easily scroll through the two lists without fear of accidentally 
deselecting anything. Figure 13-12 shows how the DualListBox might look in use. 


£: Dual List Box Tester =10/x] 
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Figure 13-12. The DualListBox in action 
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To use this custom component, create it by calling the constructor, DualListBox 
sdual = new DualListBox(), and then fill it with data by using either setSourceElements() or 
addSourceElements(); each takes either a ListModel or an array argument. The add version 
supplements the existing choices, whereas the set version clears out the choices first. When it's 
time to ask the component what the user selected, you can ask for an Iterator of the chosen 
elements with destinationIterator(). Some properties you may want to change include 
the following: 


+ The source choices” title (Available Choices in the example) 

+ The destination choices' title (Your Choices in the example) 

+ The source or destination list cell renderer 

+ The source or destination visible row count 

+ The source or destination foreground color or background color 


The complete source code for this new DualListBox component follows. Listing 13-9 
contains the first class SortedListModel, which provides a sorted ListModel. Internally, this 
takes advantage of a TreeSet. 


Listing 13-9. Sorted List Model 


import javax.swing.*; 
import java.util.*; 


public class SortedListModel extends AbstractListModel f 
SortedSet<0bject> model; 


public SortedListModel() ( 
model = new TreeSet<0bject>(); 


) 


public int getSize() ( 
return model.size(); 


) 


public Object getElementAt(int index) ( 
return model.toArray()[ index]; 


) 


public void add(Object element) ( 
if (model.add(element)) £ 
fireContentsChanged(this, 0, getSize()); 
J 
J 
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public void addA11(Object elements[]) £ 
Collection<0bject> c = Arrays.asList(elements); 
model .addAl11(c); 
fireContentsChanged(this, 0, getSize()); 

. 


public void clear() f 

model.clear(); 

fireContentsChanged(this, 0, getSize()); 
) 


public boolean contains(Object element) ( 
return model.contains(element); 


J 


public Object firstElement() ( 
return model.first(); 


J 


public Iterator iterator() ( 
return model.iterator(); 


J 


public Object lastElement() ( 
return model.last(); 


J 


public boolean removeElement(Object element) ( 
boolean removed = model.remove(element); 
if (removed) ( 

fireContentsChanged(this, 0, getSize()); 

) 
return removed; 

) 

J 


Listing 13-10 shows the Dua1ListBox source. The included main() method demonstrates 
the component. 
Listing 13-10. Dual List Box Sample 


import java.awt.*; 

import java.awt.event.*; 
import javax.swing.*; 
import java.util.Iterator; 


public class DualListBox extends JPanel f 
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private static final Insets EMPTY_INSETS = new Insets(0,0,0,0); 
private static final String ADD BUTTON_LABEL = "Add >>"; 
private static final String REMOVE _BUTTON_LABEL = "<< Remove"; 
private static final String DEFAULT_SOURCE_CHOICE_LABEL = 
"Available Choices"; 

private static final String DEFAULT_DEST_CHOICE_LABEL = 

"Your Choices"; 

private JLabel sourceLabel; 

private JList sourcelist; 

private SortedListModel sourceListModel; 

private JList destList; 

private SortedListModel destListModel; 

private JLabel destLabel; 

private JButton addButton; 

private JButton removeButton; 


public DualListBox() 4 
initScreen(); 
) 
public String getSourceChoicesTitle() ( 
return sourceLabel.getText(); 
) 
public void setSourceChoicesTitle(String newValue) ( 
sourceLabel.setText(newValue); 
) 
public String getDestinationChoicesTitle() ( 
return destLabel.getText(); 
) 
public void setDestinationChoicesTitle(String newValue) ( 
destlLabel.setText(newValue); 
) 
public void clearSourceListModel() f 
sourceListModel.clear(); 
) 
public void clearDestinationListModel() f 
destListModel.clear(); 
) 
public void addSourceElements(ListModel newValue) f 
fillListModel(sourceListModel, newValue); 
) 
public void setSourceElements(ListModel newValue) f 
clearSourceListModel(); 
addSourceElements(newValue); 
) 
public void addDestinationElements(ListModel newValue) ( 
fillListModel(destListModel, newValue); 


J 
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private void filllListModel(SortedListModel model, ListModel newValues) ( 
int size = newValues.getSize(); 
for (int i=0; i<size; i++) [ 
model .add(newValues .getElementAt(1)); 


public void addSourceElements(Object newValue[]) ( 
illlListModel(sourcelListModel, newValue); 


—h 


public void setSourceElements(Object newValue[]) ( 
clearSourceListModel (); 
addSourceElements(newValue); 


public void addDestinationElements (Object newValue[ ]) ( 
fillListModel(destListModel, newValue); 

) 

private void fillListModel(SortedListModel model, Object newValues[]) ( 
model .addA11(newValues); 

) 

public Iterator sourcelterator() ( 

return sourceListModel.iterator(); 

) 

public Iterator destinationlterator() 1 

return destListModel.iterator(); 

) 

public void setSourceCellRenderer(ListCellRenderer newValue) £ 

sourceList.setCellRenderer(newValue); 

) 

public ListCellRenderer getSourceCellRenderer() ( 

return sourceList.getCellRenderer(); 

) 

public void setDestinationCellRenderer(ListCellRenderer newValue) ( 

destList.setCellRenderer(newValue); 

) 

public ListCellRenderer getDestinationCellRenderer() ( 

return destlist.getCellRenderer(); 


J 


public void setVisibleRowCount(int nenValue) f 
sourceList.setVisibleRowCount(newValue); 
destList.setVisibleRowCount(newValue); 

) 

public int getVisibleRowCount() ( 
return sourceList.getVisibleRowCount (); 


J 
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public void setSelectionBackground(Color newValue) ( 
sourceList.setSelectionBackground(newValue); 
destList.setSelectionBackground(newValue); 

) 

public Color getSelectionBackground() ( 
return sourceList.getSelectionBackground(); 

) 

public void setSelectionForeground(Color newValue) ( 
sourceList.setSelectionForeground(newValue); 
destList.setSelectionForeground(newValue); 

) 

public Color getSelectionForeground() ( 
return sourceList.getSelectionForeground(); 

) 

private void clearSourceSelected() f 
Object selected[] = sourceList.getSelectedValues(); 
for (int i=selected.length-1; i >= 0; --i) [ 

sourcelListModel.removeElement(selected[i]); 


J 


sourceList.getSelectionModel().clearselection(); 
) 
private void clearDestinationSelected() ( 
Object selected[] = destList.getSelectedValues(); 
for (int i=selected.length-1; i >= 0; --i) [ 
destListModel.removeElement(selected[i]); 
) 
destList.getSelectionModel().clearSelection(); 
) 
private void initScreen() ( 
setBorder(BorderFactory.createEtchedBorder()); 
setLayout(new GridBagLayout()); 
sourcelabel = new JLabel(DEFAULT SOURCE CHOICE LABEL); 
sourceListModel = new SortedListModel(); 
sourcelList = new JList(sourcelListModel); 
add(sourceLabel, 
new GridBagConstraints(0, 0, 1, 1, 0, O, GridBagConstraints.CENTER, 
GridBagConstraints.NONE, EMPTY_INSETS, O, 0)); 
add(new JscrollPane(sourceList), 
new GridBagConstraints(0, 1, 1, 5, .5, 1, GridBagConstraints.CENTER, 
GridBagConstraints.BOTH, EMPTY_INSETS, O, 0)); 


addButton = new JButton(ADD BUTTON LABEL); 
add(addButton, 
new GridBagConstraints(1, 2, 1, 2, 0, .25, GridBagConstraints.CENTER, 
GridBagConstraints.NONE, EMPTY_INSETS, O, 0)); 
addButton.addActionListener(new AddListener()); 
removeButton = new JButton(REMOVE BUTTON_LABEL); 
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add(removeButton, 
new GridBagConstraints(1, 4, 1, 2, 0, .25, GridBagConstraints.CENTER, 
GridBagConstraints.NONE, new Insets(0,5,0,5), 0, 0)); 
removeButton.addActionListener(new RemoveListener()); 


destlabel = new JLabel(DEFAULT DEST_CHOICE LABEL); 
destListModel = new SortedListModel(); 
destList = new JList(destListModel); 
add(destLabel, 
new GridBagConstraints(2, 0, 1, 1, 0, O, GridBagConstraints.CENTER, 
GridBagConstraints.NONE, EMPTY_INSETS, 0, 0)); 
add(new JScrollPane(destList), 
new GridBagConstraints(2, 1, 1, 5, +5, 1.0, GridBagConstraints.CENTER, 
GridBagConstraints.BOTH, EMPTY_INSETS, 0, 0)); 


J 


private class AddListener implements ActionListener ( 
public void actionPerformed(ActionEvent e) ( 
Object selected[] = sourceList.getSelectedValues(); 
addDestinationElements(selected); 
clearSourceselected(); 
) 
) 


private class RemoveListener implements ActionListener ( 
public void actionPerformed(ActionEvent e) ( 
Object selected[] = destList.getSelectedValues(); 
addSourceElements(selected); 
clearDestinationselected(); 
) 
) 


public static void main(String args[]) ( 
Runnable runner = new Runnable() 4 
public void run() £ 

JFrame frame = new JFrame("Dual List Box Tester"); 
frame.setDefaultClose0peration(JFrame.EXIT_ON CLOSE); 
DualListBox dual = new DualListBox(); 
dual.addSourceElements( 

new String[] ("One", "Two", "Three")); 
dual.addSourceElements( 

new String[] ("Four", "Five", "Six")); 
dual.addSourceElements( 

new String[] ("Seven", "Eight", "Nine")); 
dual.addSourceElements( 

new String[] ("Ten", "Eleven", "Twelve")); 
dual.addSourceElements( 

new String[] ("Thirteen", "Fourteen", "Fifteen")); 
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dual.addSourceElements ( 
new String[] (["Sixteen", "Seventeen", "Eighteen")); 
dual.addSourceElements ( 
new String[] ("Nineteen", "Twenty", "Thirty")); 
frame.add(dual, BorderLayout.CENTER); 
frame.setSize(400, 300); 
frame.setVisible(true); 
) 
E 
EventQueue.invokeLater(runner); 
) 
) 


Adding Element-Level Tooltips to List Items 


As described in Chapter 4, all Swing components support displaying tooltip text. By calling the 
setToo1TipText() method of a component, you can display any single text string over that 
component. Inthe case ofa JList component (or for that matter, any component that contains 
multiple items such as a JTree or JTable), this single tooltip text string may not be sufficient. 
You may wish to display a different tip over each item in a component. 

Displaying item-level tips takes a little more work. To display different tooltip text over 
each item, you must create a subclass of JList. From within this subclass, you must manually 
register the component with the Too1TipManager. This is normally done for you when you call 
setToo1TipText(). But, because you won't be calling this method, you must manually notify 
the manager, as follows: 


ToolTipManager.sharedInstance().registerComponent (this); 


After you notify the Too1TipManager, the manager will then notify the component when- 
ever the mouse moves over the component. This allows you to override the public String 
getToolTipText(MouseEvent mouseEvent) method to provide the appropriate tip for the item 
under the mouse pointer. Using some kind of Hashtable, HashMap, or Properties list allows you 
to map the item the mouse is over to item-specific tooltip text. 


public String getTool1TipText(MouseEvent event) ( 
Point p = event.getPoint(); 
int location = locationToIndex(p); 
String key = (String)model.getElementAt (location); 
String tip = tipProps.getProperty(key); 
return tip; 


Figure 13-13 shows how the PropertiesList example class demonstrates various tooltips 
based on whichever element the mouse pointer is resting over. The complete source for the 
example follows in Listing 13-11. 
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awt.toolkit <= ljava.version [a 
ffile.encoding ljava.vm.info 

ffile.encoding.pkg E java um.name 

[file.separator java.vm.sBacilication aaa 
java.awt.grapbicsenv lava mn. pea EOISpOICT Client] 
java.avwt.pril da — ljava.um.specification.version 

B sun.awtWin32GraphicsEnvironment] Ñ 

java.class.p: ljavavm.vendor 

paco ljava.vm.version 

java.endorsed.dirs line.separator 3 
java.ext.dirs ps.arch 

java.home 'os.name A 
java.io.tmpdir '0S.version 

java.library.path path.separator 

java.runtime.name sun.arch.data.model 

[java.runtime.version sun.boot.class.path | 


Figure 13-13. A JList with different element-level tooltip text 


Listing 13-11. Custom Tooltips for List Elements 


import java.awt.*; 
import java.awt.event.*; 
import java.util.*; 
import javax.swing.*; 


public class PropertiesList extends JList ( 


SortedListModel model; 
Properties tipProps; 


public PropertiesList(Properties props) ( 
model = new SortedListModel(); 
setModel (model); 
ToolTipManager.sharedInstance().registerComponent (this); 


tipProps = props; 
addProperties(props); 
y 
private void addProperties(Properties props) 1 
// Load 
Enumeration names = props.propertyNames(); 
while (names.hasMoreElements()) ( 
model .add(names .nextElement()); 
y 
y 
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public String getToolTipText(MouseEvent event) ( 
Point p = event.getPoint(); 


int location = locationToIndex(p); 
String key = (String)model.getElementAt (location); 
String tip = tipProps.getProperty(key); 
return tip; 
J 


public static void main (String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("Custom Tip Demo"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
Properties props = System.getProperties(); 
Propertieslist list = new PropertiesList(props); 
JScrollPane scrollPane = new JScrollPane(list); 
frame.add(scrollPane); 
frame.setSize(300, 300); 
frame.setVisible(true); 
4 
5 
EventQueue.invokeLater(runner); 
J 
) 


JComboBox Class 


The JComboBox component of the Swing component set is a multiple-part component that 
allows a user to choose from a predefined set of choices with the help of a pull-down list. In its 
basic configuration, a JComboBox acts like a JLabel to display the current user selection. Embedded 
within the JLabel is a pop-up menu containing choices within a JList control. When the 
desired choice isn't available, the JComboBox can use a JTextField to enter a new choice. The 
JList partis automatically embedded within a JScrol1Pane when desired; you don't need to 
manually create the JList or place itin the JScrol1Pane. In addition, the text field for editing is 
disabled by default, permitting a user to select from the set of predefined choices only. Figure 13-14 
illustrates two JComboBox components: one that is not editable showing its list of choices, and 
another that is editable and not showing its choices. 


Chardonnay 


Figure 13-14. Sample JComboBox components 
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Four essential elements define the JComboBox component and its implementation: 
+ A data model for holding the JComboBox data, as defined by the ListModel interface 


+ A cell renderer for drawing the elements of the JComboBox, as described by the 
ListCellRenderer interface 


+ An editor for entering choices not part of the predefined data model, as defined by the 
ComboBoxEditor interface 


+ Akeystroke manager for handling keyboard input to select elements ofthe JComboBox, as 
described by the KeySelectionManager interface 


Many of the JComboBox capabilities are shared with the JList component. This isn't accidental; 
the two components are fairly similar. Let's now look at the JComboBox in more detail. 


Creating JComboBox Components 


Like the JList component, the JComboBox component has four constructors, allowing you to 
create one based on your initial data structure. Unlikethe JList component, the default model 
used by the array and Vector constructor permits adding and removing data elements. 


public JComboBox() 
JComboBox comboBox = new JComboBox(); 


public JComboBox(Object listData[]) 

String labels[] = £ "Chardonnay", "Sauvignon", "Riesling", "Cabernet", "Zinfandel", 
"Merlot", "Pinot Noir", "Sauvignon Blanc", "Syrah", "Gewúrztraminer"); 

JComboBox comboBox = new JComboBox(labels); 


public JComboBox(Vector listData) 
Vector vector = aBufferedImage.getSources(); 
JComboBox comboBox = new JComboBox(vector); 


public JComboBox(ComboBoxModel model) 
ResultSet results = aJDBCStatement.executeQuery ("SELECT columnName FROM tableName"); 
DefaultComboBoxModel model = new DefaultComboBoxModel (>); 
while (result.next()) 
model. addElement (results .getString(1)); 
JComboBox comboBox = new JComboBox(model); 


JComboBox Properties 


After you create a JComboBox component, you can modify each ofits many properties. Table 13-10 
shows the 22 properties of JComboBox. 
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Table 13-10. JComboBox Properties 


Property Name 


accessibleContext 
action 
actionCommand 
actionListeners 
editable 

editor 

enabled 

itemCount 
itemListeners 
keySelectionManager 
lightWeightPopupEnabled 
maximumRowCount 
model 
popupMenuListeners 
popupVisible 
prototypeDisplayValue 
renderer 
selectedIndex 
selectedItem 
selectedObjects 

UI 

UIClassID 


The significant properties ofthe JComboBox are concerned with the display of the pop-up 
list. You can control the maximum number of visible entries in the pop-up list by setting the 
maximumRowCount property. The lightWeightPopupEnabled property setting helps determine the 
type of window to use when displaying the pop-up menu of choices. Ifthe component fits 
completely within the top-level window of the program, the component will be lightweight. 


Data Type 
AccessibleContext 
Action 

String 
ActionListener[ ] 
boolean 
ComboBoxEditor 
boolean 

int 

ItemListener[ ] 
JComboBox.KeySelectionManager 
boolean 

int 

ComboBoxModel 
PopupMenuListener[ ] 
boolean 

Object 
ListCellRenderer 
int 

Object 

Object[ ] 
ComboBoxUI 


String 


Access 
Read-only 


Read-write bound 
Read-write 
Read-only 
Read-write bound 
Read-write bound 
Write-only bound 
Read-only 
Read-only 
Read-write 
Read-write 
Read-write bound 
Read-write bound 
Read-only 
Read-write 
Read-write bound 
Read-write bound 
Read-write 
Read-write 
Read-only 
Read-write 


Read-only 


Ifit doesn't fit, it will be heavyweight. Ifyou're mixing AWT and Swing components in 
a program, you can force the pop-up menu of choices to be heavyweight by setting the 


lightWeightPopupEnabled property to true. This will force the pop-up to appear above other 
components. The remaining property related to the pop-up listis the popupVisible property, 


which allows you to programmatically display the pop-up list. 


CHAPTER 13 LIST MODEL CONTROLS 


Note Besides setting the popupVisible property, you can use the public void hidePopup() and 
public void showPopup() methods to toggle the pop-up list's visibility status. 


Rendering JComboBox Elements 


The rendering of elements within a JComboBox is done with a ListCellRenderer. This is the same 
renderer that is used for a JList component. Once you've created a renderer for either one of 
these two components, you can use that renderer for the other component. To reuse the 
ComplexCellRenderer from earlier in the chapter (Listing 13-6), you could add the following 
lines to the ComplexRenderingSample example (Listing 13-7) to have the two components share 
the same renderer. 


JComboBox comboBox = new JComboBox(elements); 
comboBox.setRenderer(renderer); 
frame.add(comboBox, BorderLayout.NORTH); 


The result of adding these lines is shown in Figure 13-15. 


l0lx 
pm 
+ Help > 

Me 
+ 


11 


4 Trapped 


Figure 13-15. A JComboBox with a custom renderer 


Not all renderers will work as expected with both the JComboBox and JList components. 
For instance, the FocusedTitleListCellRenderer demonstrated earlier in Figure 13-6 wouldn't 
show the “Focused” title border in a JComboBox because the choices never had the input focus. 
In addition, different components may have different default colors (a different unselected 
background color, in this case). It may be necessary to ask what color the component normally 
would be rendered in, and then act accordingly. 


Selecting JComboBox Elements 


The JComboBox component supports at least three different events related to selection. 
You can listen for keyboard input to support key selection with the help ofthe JComboBox. 
KeySelectionManager class. You can also listen with an ActionListener or an ItemListener 
to find out when the selected item of the JComboBox changes. 

If you want to programmatically select an element, use public void 
setSelectedItem(Object element) or public void setSelectedIndex(int index). 


493 


494 


CHAPTER 13 LIST MODEL CONTROLS 


Tip To programmatically deselect the current choice of a JComboBox, call setSelectedIndex() with an 
argument of —1. 


Listening to Keyboard Events with a KeySelectionManager 


The JComboBox has a public inner interface that's fairly important. KeySelectionManager, andits 
default implementation, manages selection from the keyboard of items within the JComboBox. 
The default manager locates the next element that corresponds to the pressed key. It has 
memory, so if you have entries that start with similar prefixes, users can continue typing until 
there is enough of a match to be unique. If you don't like this behavior, you can either turn it 
off or create a new key selection manager. 


Note The KeySelectionManager works only in combo boxes that are not editable. 


If you want to turn off the key-selection capabilities, you can't do so by simply setting the 
keySelectionManager property to null. Instead, you must create an implementation of the 
interface with an appropriate method. The single method of the interface is public int 
selectionForKey(char aKey, ComboBoxModel aModel). In the event the pressed key doesn't 
match any elements, the routine needs to return —1. Otherwise, it should return the position of 
the matched element. So, to ignore keyboard input, the routine should always return —1, as 
shown here: 


JComboBox.KeySelectionManager manager = 
new JComboBox.KeySelectionManager() ( 
public int selectionForKey(char aKey, ComboBoxModel aModel) ( 
return -1; 
J 
b 


aJcombo.setKeySelectionManager (manager); 


Listening to JComboBox Events with an ActionListener 


The primary means of listening for selection events is through an ActionListener, possibly set 
with setAction(Action). It will tell you when an element has been selected within a JComboBox. 
Unfortunately, the listener doesn't know which element is selected. 


Note Setting the ActionListener through setAction(Action) also configures the tooltip text and the 
enabled state of the JComboBox based on the Action. 
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Because the ActionListener can't identify the selected element, it must ask the JComboBox 
that served as the source of the event. To determine the selected element from the JComboBox, 
use either getSelectedItem() or getSelectedIndex(). Ifan index of —1 is returned, then the 
currently selected item isn't part of the model. This seemingly impossible situation happens 
when the JComboBox is editable and the user has entered a value that isn't part of the original 
model. 


Note The text string comboBoxChanged is the action command for the ActionEvent sent to the 
ActionListener when an item within a JComboBox changes. 


Listening to JcomboBox Events with an ItemListener 


If you use an ItemListener to find out when the selected item within a JComboBox changes, 
you'll also learn which item was deselected. 

To demonstrate both the ActionListener and the ItemListener, the program shown in 
Listing 13-12 attaches both of them to the same JComboBox. The ActionListener prints its 
“action command,” as well as the currently selected item. The ItemListener prints the affected 
item and the state change for it, as well as the currently selected item. 


Listing 13-12, JComboBox Selection Sample 


import javax.swing.*; 
import javax.swing.event.*; 
import java.awt.*; 

import java.awt.event.*; 
import java.io.*; 


public class SelectingComboSample ( 
static private String selectedString(ItemSelectable is) f 
Object selected[] = is.getSelectedObjects(); 
return ((selected.length == 0) ? "null" : (String)selected[0]); 
y 


public static void main(String args[]) ( 
Runnable runner = new Runnable() 4 
public void run() £ 

String labels[] = ("Chardonnay", "Sauvignon", "Riesling", "Cabernet", 
"Zinfandel", "Merlot", "Pinot Noir", "Sauvignon Blanc", "Syrah", 
"Gewirztraminer”); 

JFrame frame = new JFrame("Selecting JComboBox"); 

frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


JComboBox comboBox = new JComboBox(labels); 
frame. add(comboBox, BorderLayout .SOUTH); 
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final JTextArea textArea = new JTextArea(); 
textArea.setEditable(false); 

JScrollPane sp = new JScrollPane(textArea); 
frame.add(sp, BorderLayout.CENTER); 


ItemListener itemListener = new ItemListener() f 
public void itemStateChanged(ItemEvent itemEvent) ( 
StringWriter sw = new StringWriter(); 
PrintWriter pw = new PrintWriter(sw); 
int state = itemEvent.getStateChange(); 
String stateString = 
((state == ItemEvent.SELECTED) ? "Selected" : "Deselected”); 
pw.print("Item: " + itemEvent.getItem()); 
pw.print(", State: " + stateString); 
ItemSelectable is = itemEvent.getItemSelectable(); 
pw.print(", Selected: " + selectedString(is)); 
pw.println(); 
textArea.append(sw.toString()); 
) 
E 


comboBox.addItemListener(itemListener); 


ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
StringWriter sw = new StringWriter(); 
PrintWriter pw = new PrintWriter(sw); 
pw.print("Command: " + actionEvent.getActionCommand()); 
ItemSelectable is = (ItemSelectable)actionEvent.getSource(); 
pw.print(", Selected: " + selectedString(is)); 
pw.println(); 
textArea.append(sw.toString()); 
y 
E 


comboBox.addActionListener(actionListener); 


frame.setSize(400, 200); 
frame.setVisible(true); 
) 
E 
Event0Queue.invokeLater(runner); 
J 
) 


Figure 13-16 shows the results after the program has been running for some time. 
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£ Selecting JComboBox 3 10 ÍxÍ 


ltern: Cabernet, State: Selected, Selected: Cabernet 
Command: comboBoxChanged, Selected: Cabernet 
ltern: Cabernet, State: Deselected, Selected: Syrah 
ltern: Syrah, State: Selected, Selected: Syrah 
Command: comboBoxChanged, Selected: Syrah 
ltern: Syrah, State: Deselected, Selected: Pinot Noir 
ltern: Pinot Noir, State: Selected, Selected: Pinot Noir 
Command: comboBoxChanged, Selected: Pinot Noir 


> 


Pinot Noir [y 


Figure 13-16. Listening for JComboBox selections 


Listening to JComboBox Events with a ListDataListener 


You can attach a ListDataListener to the data model of the JComboBox. This listener would then 
be notified when the selected element ofthe model changes. Unfortunately, the listener would 
also be notified of other data model changes. In other words, using a ListDataListener to find 
out when an element of a JComboBox is selected is not a recommended option. 


Note Mouse movement and cursor movement events within a JComboBox don't change the selected 
entry; mouse release events do change the selected entry. Any registered listeners would be notified when a 
selected mouse button is released over an element within the JComboBox pop-up list. 


Editing JComboBox Elements 


You may want to use a combo box like a text field in which you list the most likely text input 
from the user, but also allow the user to enter something else. By enabling the editable property 
ofthe JComboBox, you've added this capability. To demonstrate, Figure 13-17 shows an editable 
JComboBox. The window also contains a text area that reports the current selected item and 
index. Even ifyou manually enter one of the choices within the JComboBox, getSelectedIndex() 
will report the proper position. Remember that if you enter a value that's not present, 
getSelectedIndex() returns —1. 


£] Editable JComboBox 1 - 101 xf 
'Sauvignon Blanc 52 
Selected: Gewúrztraminer, Position: 9 ¡[8 


Selected: Gewúrztraminer, Position: 9 
Selected: Chardonnay, Position: O 
Selected: Bordeaux, Position: -1 
Selected: Bordeaux, Position: -1 
Selected: Sauvignon, Position: 1 


Selected: Sauvignon Blanc, Position: 7 o 
Selected: Sauvignon Blanc, Position: 7 


Figure 13-17. Using an editable JComboBox 


The source for the example in Figure 13-17 is shown in Listing 13-13. 
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Listing 13-13. Editable JComboBox Sample 


import java.awt.*; 
import javax.swing.*; 
import java.awt.event.*; 
public class EditComboBox ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 

String labels[] = ("Chardonnay", "Sauvignon", "Riesling", "Cabernet", 
"Zinfandel”, "Merlot", "Pinot Noir", "Sauvignon Blanc", "Syrah", 
"Gewirztraminer"); 

JFrame frame = new JFrame("Editable JComboBox"); 

frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


final JComboBox comboBox = new JComboBox(labels); 
comboBox.setMaximumRowCount (5); 
comboBox.setEditable(true); 

frame.add(comboBox, BorderLayout.NORTH); 


final JTextArea textArea = new JTextArea(); 
JScrollPane scrollPane = new JScrollPane(textArea); 
frame.add(scrollPane, BorderLayout.CENTER); 


ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
textArea.append("Selected: " + comboBox.getSelectedItem()); 
textArea.append(", Position: " + comboBox.getSelectedIndex()); 
textArea.append(System.getProperty("line.separator")); 
) 
E 


comboBox.addActionListener(actionListener); 


frame.setSize(300, 200); 
frame.setVisible(true); 
) 
E 
EventQueue.invokeLater(runner); 
J 
) 


By default, the input field provided for editingis a JTextField. The default JTextField 
serves as a good editor if your data model consists of text strings. However, once your model 
contains a different type of object (for example, colors), you need to provide a different editor. 
By default, once you type in the text field (editing the results of toString() for your element), 
the objectis treated as a String. Technically, a different editor isn't always necessary. Ifyou can 
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parse the contents of the text field as a string to the proper data type, then do that. But, if you 
want to restrict the input in any manner (for example, allow only numeric input) or provide a 
better input mechanism, you must provide your own editor. The interface that defines the 
necessary behavior is called ComboBoxEditor and its definition is shown here. 


public interface ComboBoxEditor ( 
// Properties 
public Component getEditorComponent(); 
public Object getItem(); 
public void setItem(Object an0bject); 
// Listeners 
public void addActionListener(ActionListener 1); 
public void removeActionListener(ActionListener 1); 
// Other methods 
public void selectAl1(); 


Note The default editor is the BasicComboBoxEditor implementation in the javax.swing.plaf.basic 
package. 


The add/remove listener methods are necessary for notifying any listeners when the 
ComboBoxEditor value has changed. It's not necessary for you to add a listener, and normally 
you won't do that. Nevertheless, the methods are part of the interface, so they”'1l need to be 
implemented if you want to provide your own editor. 

The getEditorComponent () method returns the Component object used for the editor. You 
can use either an AWT or a Swing component for the editor (for example, a JColorChooser for 
color selection). The selectA11() method is called when the editor is first shown. It tells the 
editor to select everything within it. Selecting everything allows a user to merely type over the 
current input for the default JTextField case. Some editors may not require use of this method. 

The item property methods demand the most work when you're providing a custom 
editor. You'll need to supply a method to map the specific pieces of the Object subclass to the 
components in order to present the data to be edited. You then need to get the data from the 
editor so that the data can be stored back in an instance of the original object. 

To demonstrate, the source code in Listing 13-14 is a ComboBoxEditor for the Color class. 
A custom editor is necessary because there's no automatic way to parse the results of editing 
the default string shown for a Color. This editor will use a JColorChooser for the user to pick 
a new color value. The getItem() method needs to return only the current value, a Color. 

The setItem() method needs to convert the object passed to a Color object; the argument to 
setItem() is an Object. The setItem() method could be made to accept only Color arguments. 
However, for this example, any string that's decodable with the Color.decode() method is also 
supported. 
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Listing 13-14. 4 Color Combo Box Editor 


import java.awt.*; 
import javax.swing.*; 
import javax.swing.event.*; 
import java.awt.event.*; 
public class ColorComboBoxEditor implements ComboBoxEditor ( 
final protected JButton editor; 
protected EventListenerlist listenerlist = new EventListenerList(); 
public ColorComboBoxEditor(Color initialColor) f 
editor = new JButton(""); 
editor.setBackground(initialColor); 
ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent e) ( 
Color currentBackground = editor.getBackground(); 
Color color = JColorChooser.showDialog( 
editor, "Color Chooser", currentBackground); 
if ((color != null) 38 (currentBackground != color)) ( 
editor.setBackground(color); 
fireActionEvent(color); 


J 


) 
y; 
editor.addActionListener(actionListener); 
) 
public void addActionListener(ActionListener 1) ( 
listenerlList.add(Actionlistener.class, 1); 
) 
public Component getEditorComponent() ( 
return editor; 
) 
public Object getlItem() ( 
return editor.getBackground(); 
) 
public void removeActionListener(ActionListener 1) ( 
listenerList.remove(ActionlListener.class, 1); 
) 
public void selectAl1() £ 
// Ignore 
) 
public void setItem(Object newValue) ( 
if (newValue instanceof Color) f 
Color color = (Color)newValue; 
editor.setBackground(color); 
+ else f 
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// Try to decode 
try ( 
Color color = Color.decode(newValue.toString()); 
editor.setBackground(color); 
) catch (NumberFormatException e) ( 
// Ignore - value unchanged 
) 
) 
) 
protected void fireActionEvent(Color color) ( 
Object listeners[] = listenerList.getListenerlist(); 
for (int i = listeners.length-2; i>=0; i-=2) ( 
if (listeners[i] == ActionListener.class) ( 
ActionEvent actionEvent = 
new ActionEvent(editor, ActionEvent.ACTION PERFORMED, color.toString()); 
((ActionListener)listeners[i+1]).actionPerformed(actionEvent); 
) 
) 
) 
n 


To use the new editor, you need to associate it with a JComboBox. After you change the 
EditComboBox example shown earlier (Listing 13-13) to make the data model consist of an array 
of Color objects, you can then install the editor by adding the following: 


Color color = (Color)comboBox.getSelectedItem(); 
ComboBoxEditor editor = new ColorComboBoxEditor(color); 
comboBox.setEditor(editor); 


A complete test program follows in Listing 13-15. It's different from the EditComboBox 
because below the JComboBox is a JLabel that stays in sync with the currently selected color of 
the JComboBox. There's also a custom cell renderer that sets the background color to the value 
of the cell. 


Listing 13-15. Custom JComboBox Editor Sample 


import java.awt.*; 
import javax.swing.*; 
import java.awt.event.*; 
public class ColorComboBox ( 
static class ColorCellRenderer implements ListCellRenderer ( 
protected DefaultListCellRenderer defaultRenderer = 
new DefaultListCellRenderer(); 
// Width doesn't matter as the combo box will size 
private final static Dimension preferredSize = new Dimension(0, 20); 
public Component getListCellRendererComponent(JList list, Object value, 
int index, boolean isSelected, boolean cellHasFocus) f 
JLabel renderer = (JLabel)defaultRenderer.getListCellRendererComponent ( 
list, value, index, isSelected, cellHasFocus); 
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if (value instanceof Color) ( 
renderer.setBackground((Color)value); 

) 

renderer.setPreferredSize(preferredSize); 

return renderer; 


public static void main(String args[]) ( 
Runnable runner = new Runnable() f 


public void run() ( 

Color colors[] = [Color.BLACK, Color.BLUE, Color.CYAN, Color.DARK_GRAY, 
Color.GRAY, Color.GREEN, Color.LIGHT_GRAY, Color.MAGENTA, 
Color.ORANGE, Color.PINK, Color.RED, Color.WHITE, Color.YELLOW); 

JFrame frame = new JFrame("Color JComboBox"); 

frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


final JComboBox comboBox = new JComboBox(colors); 
comboBox.setMaximumRowCount (5); 
comboBox.setEditable(true); 

comboBox.setRenderer(new ColorCellRenderer()); 

Color color = (Color)comboBox.getSelectedItem(); 
ComboBoxEditor editor = new ColorComboBoxEditor(color); 
comboBox.setEditor(editor); 

frame.add(comboBox, BorderLayout.NORTH); 


final JLabel label = new JLabel(); 
label.setOpaque(true); 
label.setBackground((Color)comboBox.getSelectedItem()); 
frame.add(label, BorderLayout.CENTER); 


ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
Color selectedColor = (Color)comboBox.getSelectedItem(); 
label.setBackground(selectedColor); 
) 
E 


comboBox.addActionListener(actionListener); 


frame.setSize(300, 200); 
frame.setVisible(true); 


; 


EventQueue.invokeLater(runner); 


Figure 13-18 shows the screen and a visible editor. 
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£ Color Chooser xl 


[Swatches | HSB [RGB | 


£: Color JComboBox 


java.awt.Color[r=255,9=200,b=0] 
java.awt.Color[r=255,9=175,b=175] Preview 


O Sample Text Sample Text 


Cancel Reset 


java.awt.Color[r=255,9=255,b=255] 
java.awt.Color[r=255,9=255,b=0] 


Figure 13-18. Using a custom ComboBoxEditor 


Customizing a JComboBox Look and Feel 


Each installable Swing look and feel provides a different JComboBox appearance and set of 
default UTResource value settings for the component. Figure 13-19 shows the appearance ofthe 
JComboBox component for the preinstalled set of look and feel types: Motif, Windows, and Ocean. 


1012 
Riesling y 


Chardonnay 
Motif 
101] 
[Riesling 5A | 


1] 
[Chardonnay 


Ocean 


Figure 13-19. JComboBox under different look and feel types 
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The available set ofUTResource-related properties for a JComboBox is shown in Table 13-11. 
The JComboBox component has 21 different properties. 


Table 13-11. JComboBox UlResource Elements 


Property String Object Type 
ComboBox. actionMap ActionMap 
ComboBox.ancestorInputMap InputMap 
ComboBox. background Color 
ComboBox. border Border 
ComboBox.buttonBackground Color 
ComboBox.buttonDarkShadow Color 
ComboBox.buttonHighlight Color 
ComboBox. buttonShadow Color 
ComboBox.control Color 
ComboBox.controlForeground Color 
ComboBox.disabledBackground Color 
ComboBox.disabledForeground Color 
ComboBox. font Font 
ComboBox.foreground Color 
ComboBox.rendererUselListColors Boolean 
ComboBox.selectionBackground Color 
ComboBox.selectionForeground Color 
ComboBox.showPopupOnNavigation Boolean 
ComboBox.timeFactor Long 
ComboBox.togglePopupText String 
ComboBoxUI String 


Changing the pop-up icon is one example of customizing the look and feel. To do this, 
you'll need to install a new user interface. (This process is discussed at length in Chapter 20.) 
Basically, you inherit the default functionality from either the BasicComboBoxUI or MetalComboBoxUI 
user interface delegate, and then override only the protected JButton createArrowButton() 
method. 

Figure 13-20 shows the results of this change to the JComboBox user interface. 


[2 popup 2combodos AA 
» 


Chardonnay 
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Figure 13-20. Altering the JComboBox pop-up button 


The source for the JComboBox example shown in Figure 13-20 follows in Listing 13-16. 


Listing 13-16. Custom JComboBox Pop-up Button 


import java. 


awt.*; 


import javax.swing.*; 
import javax.swing.plaf.*; 
import javax.swing.plaf.basic.*; 
public class PopupComboSample ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() £ 
public void run() £ 
String labels[] = ("Chardonnay", "Sauvignon", "Riesling", "Cabernet", 
"Zinfandel", "Merlot", "Pinot Noir", "Sauvignon Blanc", "Syrah", 
"Gewirztraminer”); 
JFrame frame = new JFrame("Popup JComboBox”); 


fra 


JCo! 


e.setDefaultCloseO0peration(JFrame.EXIT_ON_ CLOSE); 


boBox comboBox = new JComboBox(labels); 


comboBox.setMaximumRowCount (5); 
comboBox. setUI ((ComboBoxUI)MyComboBoxUI .createUI (comboBox)); 


fra 


fra 
fra 
) 
$; 


e.add(comboBox, BorderLayout.NORTH) ; 


e.setSize (300, 200); 
e.setVisible (true); 


EventQueue.invokeLater(runner); 


J 


static class MyComboBoxUI extends BasicComboBoxUI ( 
public static ComponentUI createUI(JComponent c) ( 
return new MyComboBoxUI(); 


J 
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protected JButton createArrowButton() 1 
JButton button = new BasicArrowButton(BasicArrowButton.EAST); 
return button; 
) 
J 
) 


Sharing the Data Model for a JcomboBox 
and JList 


You may have noticed several similarities between the parts that make up the JComboBox and 
JList. You can use the same data model and same renderer for both components. You've 
already seen how to share a renderer between components, in the “Rendering JComboBox 
Elements” section earlier in this chapter. The example presented in this section demonstrates 
how you could share the same data model across several components. 

The example has two editable combo boxes and one JList, all sharing one data model. It 
also presents a button that you can click to dynamically add items to the data model. Because 
the data model will be associated with several components, you'll notice that each ofthem has 
additional options to choose from after selecting the button. Figure 13-21 shows what the 
screen might look like after adding several elements. 


£ Shared Data (01 xi 
Zinfandel y | Zinfandel] -- 
Riesling pá 77 

Merlot Sauvignon 

Sauvignon Chardonnay 
Chardonnay Pinot Noir 

Pinot Noir Riesling z 
Riesling + 


Figure 13-21. Sharing a data model across components 
Listing 13-17 shows the source for the shared data model example. 


Listing 13-17. Shared Data Model 


import java.awt.*; 

import java.awt.event.*; 

import javax.swing.*; 

public class SharedDataSample ( 

public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
final String labels[] = (["Chardonnay", "Sauvignon", "Riesling", 

"Cabernet", "Zinfandel", "Merlot", "Pinot Noir", "Sauvignon Blanc", 
"Syrah", "Gewiúrztraminer"); 
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final DefaultComboBoxModel model = new DefaultComboBoxModel (labels); 


JFrame frame = new JFrame("Shared Data"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


JPanel panel = new JPanel(); 

JComboBox comboBox1 = new JComboBox(model); 
comboBox1.setMaximumRowCount (5); 
comboBox1.setEditable(true); 


JComboBox comboBox2 = new JComboBox(model); 
comboBox2 .setMaximumRowCount (5); 
comboBox2.setEditable(true); 
panel.add(comboBox1); 

panel.add(comboBox2); 

frame.add(panel, BorderLayout.NORTH); 


Jlist jlist = new JList(model); 
JScrollPane scrollPane = new JScrollPane(jlist); 
frame.add(scrollPane, BorderLayout.CENTER); 


JButton button = new JButton("Add"); 
frame.add(button, BorderLayout. SOUTH); 
ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
int index = (int)(Math.random()*labels. length); 
model .addElement(labels[index]); 
) 
5 


button.addActionListener(actionListener); 


frame.setSize(300, 200); 
frame.setVisible(true); 
) 
5 
EventQueue.invokeLater(runner); 
) 
J 


Note When running the program shown in Listing 13-17, if you share a data model across multiple 
JComboBox components, there can't be a different selected element within each component. When an 
element is “selected” in one, it's selected in all. This seems to be a bug in the MVC design of the JComboBox. 
In addition, because a ListSelectionModel manages selection for the JList, changing the selected 
element of a JComboBox has no effect on the selected elements within a JList sharing the same model. 
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Summary 


This chapter has demonstrated how to use Swing's JList and JComboBox components. You've 
seen how both components support their own data model, renderer, selection capabilities, 
and even a custom editor for the JComboBox component. Although all these capabilities are 
customizable, each of the components is readily usable with its default configuration. 


In Chapter 14, you will start to explore the Swing text components, including JTextField 
and JTextArea. 


CHAPTER 14 


Spinner Model Controls 


l. the previous chapter, you learned how to work with the basic list controls: JList and 
JComboBox. In this chapter, you will move on to the JSpinner component, introduced with 
the 1.4 version of the JDK. 


JSpinner Class 


The JSpinner works like a cross between a JList or JComboBox component with a 
JFormattedTextField. In either the JList and JComboBox control, the user can select input from 
a predetermined set of values. The JSpinner also allows this type of selection. The other half of 
the component is the JFormattedTextField. How to display or enter the value isn't controlled 
by a list cell renderer, asin a JList; instead, you get a JFormattedTextField for entry and a 
couple of arrows on the side to navigate through the different values available for the text field. 
(The JFormattedTextField is covered in Chapters 15 and 16.) 

Figure 14-1 shows what the spinner looks like for several different types ofinput. Atthe top 
of Figure 14-1 isa JSpinner with the days ofthe week in French provided to a SpinnerListModel. 
In the middle, you have a JSpinner for a date via the SpinnerDateModel class. On the bottom is 
the JSpinner usage with the SpinnerNumberModel. Each of these three work in its own myste- 
rious way, as you'll learn later in this chapter. 


[> spinner sample ATTE 
French Days/List|mardi ¡EN 
Dates/Date 1/26/09 4:43 AM 


Numbers 0% 


Figure 14-1. JSpinner examples 


Many classes are involved when creating and manipulating JSpinner components, foremost 
the JSpinner class itself. The primary two sets of classes involved are the SpinnerModel interface, 
for containing the set of selectable items for the control, and, the JSpinner.DefaultEditor 
implementations, for catching all the selections. Thankfully, many of the other classes 
involved work behind the scenes, so, for example, once you provide the numeric range in a 
SpinnerNumberModel and associate the spinner with its model, your work is essentially done. 
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Creating JSpinner Components 


The JSpinner class includes two constructors for initializing the component: 


public JSpinner() 
JSpinner spinner = new JSpinner(); 


public JSpinner(SpinnerModel model) 
SpinnerModel model = new SpinnerListModel (args); 
JSpinner spinner = new JSpinner (model); 


You can start with no data model and associate it later with the tracking method of JSpinner. 
Alternatively, you can start up the component with a full model, in an implementation of the 
SpinnerModel interface, of which three concrete subclasses are available: SpinnerDateModel, 
SpinnerListModel, and SpinnerNumberModel, along with their abstract parent class 
AbstractSpinnerModel. Ifyou don't specify a model, the SpinnerNumberModel is used. While the 
renderer and editor for the component is a JFormattedTextField, the editing is basically done 
through a series of inner classes of JSpinner: DateEditor, ListEditor, and NumberFormat, with 
its support class in its parent DefaultEditor. 


JSpinner Properties 


In addition to creating the JSpinner object, you can certainly reconfigure it, through one of the 
nine properties listed in Table 14-1. 


Table 14-1. JSpinner Properties 


Property Name Data Type Access 
accessibleContext AccessibleContext Read-only 
changeListeners ChangeListener[ ] Read-only 

editor JComponent Read-write bound 
model SpinnerModel Read-write bound 
nextValue Object Read-only 
previousValue Object Read-only 

UI Spinnerul Read-write 
UlClassID String Read-only 


value Object Read-write 
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The value property allows you to change the current setting for the component. The 
nextValue and previousValue properties allow you to peek at entries of the model in the 
different directions, without changing the selection within the application itself. 


Listening for JSpinner Events with a ChangeListener 


The JSpinner directly supports a single type of event listener: ChangeListener. Among other 
places, the listener is notified when the commitEdit() method is called for the associated 
component, telling you the spinner value changed. To demonstrate, Listing 14-1 attaches a 
custom ChangeListener to the source used to generate the program associated with Figure 14-1. 


Listing 14-1. JSpinner with ChangeListener 


import java.awt.*; 

import javax.swing.*; 
import javax.swing.event.*; 
import java.text.*; 

import java.util.*; 


public class SpinnerSample ( 
public static void main (String args[]) ( 
Runnable runner = new Runnable() £ 
public void run() £ 

JFrame frame = new JFrame("JSpinner Sample”); 

frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 

DateFormatSymbols symbols = 
new DateFormatSymbols(Locale.FRENCH); 

Changelistener listener = new ChangeListener() ( 
public void stateChanged(ChangeEvent e) ( 

System.out.println("Source: " + e.getSource()); 

ñ 

A 


String days[] = symbols.getWeekdays(); 
SpinnerModel model1 = new SpinnerListModel (days); 
JSpinner spinner1 = new JSpinner(model1); 
spinner1.addChangeListener(listener); 

JLabel label1 = new JLabel("French Days/List"); 
JPanel panel1 = new JPanel(new BorderLayout()); 
panel1.add(label1, BorderLayout.WEST); 
panel1.add(spinner1, BorderLayout.CENTER); 
frame.add(panel1, BorderLayout.NORTH); 
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SpinnerModel model2 = new SpinnerDateModel(); 
JSpinner spinner2 = new JSpinner(model2); 
spinner2.addChangeListener(listener); 

Jlabel label2 = new JLabel("Dates/Date"); 
JPanel panel2 = new JPanel(new BorderLayout()); 
panel2.add(label2, BorderLayout.WEST); 
panel2.add(spinner2, BorderLayout.CENTER); 
frame.add(panel2, BorderLayout.CENTER); 


SpinnerModel model3 = new SpinnerNumberModel (>); 
JSpinner spinner3 = new JSpinner(model3); 
spinner3.addChangeListener(listener); 

JLabel label3 = new JLabel("Numbers"); 

JPanel panel3 = new JPanel(new BorderLayout()); 
panel3.add(label3, BorderLayout.WEST); 
panel3.add(spinner3, BorderLayout.CENTER); 
frame.add(panel3, BorderLayout.SOUTH); 


frame.setSize(200, 90); 
frame.setVisible (true); 
Í 
5 
EventQueue.invokeLater(runner); 
) 
h 


Running this program demonstrates the use of this listener (of course, you'1l find far more 
meaningful ways to use a ChangeListener). 


Customizing a JSpinner Look and Feel 


As with all Swing components, the JSpinner control has a different appearance under each of 
the system-defined look and feel types, as shown in Figure 14-2. The component primarily 
looks just like a text field; the difference is in the drawing of the arrows. 


ATTE J0lxi 


la 


French DaysiListlundi Y French Days/Listfundi = French Days/List|lundi ca! 

DatesiDate (4/30/05 244 PM | — Dates/Dateli/3oros 244 Pm Dates/Date/4/30/05 2:44 PM 

Numbers! 03 Numbers 03 Numbers bH 
Motif Windows Ocean 


Figure 14-2. JSpinner under different look and feel types 


The setof 11 UTResource properties for a JSpinner is shown in Table 14-2. These are limited 
to drawing the text field and the arrows. 


Table 14-2. JSpinner UlResource Elements 
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Property String Object Type 
Spinner.actionMap ActionMap 
Spinner.ancestorInputMap InputMap 
Spinner.arrowButtonBorder Border 
Spinner.arrowButtonInsets Insets 
Spinner.arrowButtonSize Dimension 
Spinner .background Color 
Spinner.border Border 
Spinner.editorBorderPainted Boolean 
Spinner.+font Font 
Spinner.foreground Color 
Spinnerul String 


SpinnerModel Interface 


So far, you've seen how to interact with the main JSpinner class. The SpinnerModel interface is 
the data model for the component. The definition of SpinnerModel follows: 


public interface SpinnerModel ( 
// Properties 
public Object getValue(); 
public void setValue(Object); 
public Object getNextValue(); 
public Object getPreviousValue(); 
// Listeners 
public void addChangeListener(ChangeListener); 
public void removeChangeListener(ChangeListener); 


The six methods of SpinnerModel map directly to those of JSpinner. The JSpinner methods 
just redirect the method calls to that of the model, though in the case of the listener methods, 
the event source is where you attach the listener. 


AbstractSpinnerModel Class 


The base implementation ofthe SpinnerModel interface is the AbstractSpinnerModel class. It 
provides for the management and notification of the listener list. Subclasses must implement 
the other four value-related methods of the interface. Three concrete implementations 

ofthe SpinnerModel interface are provided: SpinnerDateModel, SpinnerListModel, and 
SpinnerNumberModel 
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SpinnerDateModel Class 


As might be inferred from its name, the SpinnerDateModel provides for the selection of dates. 
This class has two constructors: one that defaults to selecting all dates and another that allows 
you to limit the range. 


public SpinnerDateModel() 
SpinnerModel model = new SpinnerDateModel/(); 
JSpinner spinner = new JSpinner (model); 


public SpinnerDateModel(Date value, Comparable start, Comparable end, 
int calendarField) 

Calendar cal = Calendar.getInstance(); 

Date now = cal.getTime(); 

cal.add(Calendar.YEAR, -50); 

Date startDate = cal.getTime(); 

cal.add(Calendar.YEAR, 100); 

Date endDate = cal.getTime(); 

SpinnerModel model = 
new SpinnerDateModel(now, startDate, endDate, Calendar.YEAR); 

JSpinner spinner = new JSpinner (model); 


Ifyou don't specify any parameters, there is no start or end point. The example shown here 
uses parameters to provide a 100-year range. The last field should be one of the following 
constants from the Calendar class: 


+ Calendar.AM_PM 

+ Calendar.DAY_OF_MONTH 
+ Calendar.DAY_OF_ WEEK 

+ Calendar.DAY OF WEEK_IN MONTH 
+ Calendar.DAY_OF_YEAR 

+ Calendar.ERA 

+ Calendar. HOUR 

+ Calendar.HOUR_OF_DAY 

+ Calendar.MILLISECOND 

+ Calendar.MINUTE 

+ Calendar .MONTH 

+ Calendar.SECOND 

+ Calendar.WEEK_OF_MONTH 
+ Calendar.WEEK_OF_YEAR 


e Calendar.YEAR 


CHAPTER 14 SPINNER MODEL CONTROLS 


Note The SpinnerDateModel does not include any of the time zone-related constants of Calendar. 
You cannot scroll through those within a JSpinner via a SpinnerDateModel. 


Table 14-3 lists the three properties from the SpinnerModel interface and four specific to 
the SpinnerDateModel. 


Table 14-3. SpinnerDateModel Properties 


Property Name Data Type Access 

calendarField int Read-write 
date Date Read-only 
end Comparable Read-write 
nextValue Object Read-only 
previousValue Object Read-only 
start Comparable Read-write 
value Object Read-only 


Typically, the only new property you'll use is for getting the final date, although all that 
does is wrap the result of getValue() in the appropriate data type. Ifyou've provided a range of 
dates to the constructor, the previous or next values will be nul1 when the current value is atan 
edge condition. 


SpinnerListModel Class 


The SpinnerListModel provides for selection from a list of entries, or at least their string repre- 
sentation. This class has three constructors: 


public SpinnerListModel() 
SpinnerModel model = new SpinnerListModel(); 
JSpinner spinner = new JSpinner(model); 


public SpinnerListModel(List<?> values) 
List<String> list = args; 

SpinnerModel model = new SpinnerListModel(list); 
JSpinner spinner = new JSpinner(model); 


public SpinnerListModel(Object[] values) 
SpinnerModel model = new SpinnerListModel (args); 
JSpinner spinner = new JSpinner(model); 
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When no arguments are provided, the model contains a single element: the string empty. 
The List version retains a reference to the list. It does not copy the list. If you change the list, 
you change the elements in the model. The array version creates a private inner class instance 
of a List that can't be added to. For both the List and array versions, the initial selection will 
be the first element. If either is empty, an 111legalArgumentException will be thrown. 

As shown in Table 14-4, the only property added beyond those from the interface is to get 
or set the list. 


Table 14-4. SpinnerListModel Properties 


Property Name Data Type Access 

list List<?> Read-write 
nextValue Object Read-only 
previousValue Object Read-only 
value Object Read-write 


SpinnerNumberModel Class 


The SpinnerNumberModel provides for the selection of a number from an open or closed range 
of values. That number can be any of the subclasses of Number, including Integer and Double. 
It has four constructors, with the first three provided just as convenience methods to the last. 


public SpinnerNumberModel() 
SpinnerModel model = new SpinnerNumberModel (>); 
JSpinner spinner = new JSpinner (model); 


public SpinnerNumberModel(double value, double minimum, double maximum, 
double stepSize) 

SpinnerModel model = new SpinnerNumberModel(50, 0, 100, .25); 

JSpinner spinner = new JSpinner (model); 


public SpinnerNumberModel(int value, int minimum, int maximum, int stepSize) 
SpinnerModel model = new SpinnerNumberModel(50, 0, 100, 1); 
JSpinner spinner = new JSpinner (model); 


public SpinnerNumberModel(Number value, Comparable minimum, Comparable maximum, 
Number stepSize) 

Number value = new Integer(50); 

Number min = new Integer(0); 

Number max = new Integer(100); 

Number step = new Integer(1); 

SpinnerModel model = new SpinnerNumberModel(value, min, max, step); 

JSpinner spinner = new JSpinner (model); 


If the minimum or maximum value is null, the range is open-ended. For the no-argument 
version, the initial value is O and step is 1. The step size is literal, so if you set the step to .333, 


there will be no rounding off. 


Table 14-5 shows the properties for SpinnerNumberModel. The added properties are the 


same as those provided by the constructor. 


Table 14-5. SpinnerNumberModel Properties 


Property Name Data Type 
maximum Comparable 
minimum Comparable 
nextValue Object 
number Number 
previousValue Object 
stepSize Number 
value Object 
Custom Models 


Typically, the available models for the JSpinner are sufficient, so you don't need to subclass. 
However, that isn't always the case. For example, you might want to use a custom model that 
wraps the SpinnerListModel—instead of stopping at the first or last element, itwraps around to 
the other end. One such implementation is shown in Listing 14-2. 


Listing 14-2. RolloverSpinnerListModel Class 


import javax.swing.*; 
import java.util.*; 


public class RolloverSpinnerListModel extends SpinnerListModel ( 
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Access 


Read-write 
Read-write 
Read-only 
Read-only 
Read-only 
Read-write 


Read-write 


public RolloverSpinnerListModel(List<?> values) ( 


super(values); 


J 


public RolloverSpinnerListModel(Object[] values) ( 


super(values); 


J 
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public Object getNextValue() ( 
Object returnValue = super.getNextValue(); 
if (returnValue == null) £ 
returnValue = getList().get(0); 
J 
return returnValue; 


J 


public Object getPreviousValue() ( 
Object returnValue = super.getPreviousValue(); 
if (returnValue == null) £ 
List list = getList(); 
returnValue = list.get(list.size() - 1); 
J 
return returnValue; 
) 
h 


JSpinner Editors 


For each of the models available for a JSpinner, a secondary support class, an inner class of 
JSpinner, is available. Whereas the model allows you to control what is selectable for the 
component, the spinner editors allow you to control how to display and edit each selectable value. 


JSpinner.DefaultEditor Class 


The setEditor() method of JSpinner allows you to have any JComponent as the editor for the 
JSpinner. While you certainly can do that, more typically, you will work with a subclass of 
JSpinner.DefaultEditor. It provides the basics you will need when working with simple editors 
based on JFormattedTextField. It contains a single constructor: 


public JSpinner.DefaultEditor(JSpinner spinner) 
JSpinner spinner = new JSpinner(); 

JComponent editor = JSpinner.DefaultEditor(spinner); 
spinner.setEditor(editor); 


As Table 14-6 shows, there are two properties for the editor. 


Table 14-6. JSpinner.DefaultEditor Properties 
Property Name Data Type Access 


spinner JSpinner Read-only 


textField JFormattedTextField Read-only 


CHAPTER 14 SPINNER MODEL CONTROLS 


Without knowing which type of model you were working with, what you might do at this 
level is change some display characteristic ofthe JFormattedTextField. More typically, though, 
you'll change a custom aspect for the model's editor. 


JSpinner.DateEditor Class 


The DateEditor allows you to customize the date display (and entry) using various aspects of 
the SimpleDateFormat class of the java.text package. See the Javadoc for SimpleDateFormat for 
a complete listing of the available formatting patterns. If you don't like the default display 
output, you can modify it by passing in a new format to the second constructor. 


public JSpinner.DateEditor(JSpinner spinner) 
SpinnerModel model = new SpinnerDateModel(); 
JSpinner spinner = new JSpinner(model); 
JComponent editor = JSpinner.DateEditor(spinner); 
spinner.setEditor(editor); 


public JSpinner.DateEditor(JSpinner spinner, String dateFormatPattern) 
SpinnerModel model = new SpinnerDateModel(); 

JSpinner spinner = new JSpinner(model); 

JComponent editor = JSpinner.DateEditor(spinner, "MMMM yyyy"); 
spinner.setEditor(editor); 


By default, the format is M/d/yy h:mm a, or 12/25/04 12:34 PM for some time on Christmas 
in 2004 (or 1904, 1804, and so on). The latter example will show December 2004. 
The editor has the two properties shown in Table 14-7. 


Table 14-7. JSpinner.DateEditor Properties 


Property Name Data Type Access 
format SimpleDateFormat Read-only 
model SpinnerDateModel Read-only 


JSpinner.ListEditor Class 


When working with the SpinnerListModel, the ListEditor provides no special formatting 
support. Instead, it offers type-ahead support. Since all entries of the model are known, the 
editor tries to match the characters the user has already entered with the start of one of those 
entries. There is only one constructor, but you should never need to access it. 


public JSpinner.ListEditor(JSpinner spinner) 


As shown in Table 14-8, ListEditor has only a single property. 
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Table 14-8. JSpinner.ListEditor Properties 


Property Name Data Type Access 
model SpinnerListModel Read-only 


JSpinner.NumberEditor Class 


The NumberEditor works in a manner similar to the DateEditor, allowing you to enter strings to 
customize the display format. Instead of working with the SimpleDateFormat, the NumberEditor 
is associated with the DecimalFormat class of the java.text package. Just like DateEditor, it has 
two constructors: 


public JSpinner.NumberEditor(JSpinner spinner) 

SpinnerModel model = new SpinnerNumberModel(50, 0, 100, .25); 
JSpinner spinner = new JSpinner (model); 

JComponent editor = JSpinner.NumberEditor(spinner); 
spinner.setEditor(editor); 


public JSpinner.NumberEditor(JSpinner spinner, String decimalFormatPattern) 
SpinnerModel model = new SpinnerNumberModel(50, 0, 100, .25); 

JSpinner spinner = new JSpinner (model); 

JComponent editor = JSpinner.NumberEditor(spinner, "+, +HO.+HH"); 
spinner.setEditor(editor); 


The second constructor usage shows the default formatting string. It will try to use commas 
if the number is large enough, and it will not show decimals if the value is a whole number. 
As shown in Table 14-9, this editor has two properties. 


Table 14-9. JSpinner.NumberEditor Properties 


Property Name Data Type Access 
format DecimalFormat Read-only 
model SpinnerNumberModel Read-only 


Summary 


In this chapter, you learned about Swing's JSpinner component. When your set of choices is 
limited to a fixed set or a range of values, a JSpinner allows you to select a value by spinning 
through the different choices. You learned how that set of choices could be provided: from a set 
of dates with the SpinnerDateModel and DateEditor, with the SpinnerListModel and ListEditor, 
or via the SpinnerNumberModel and NumberEditor. 

Chapter 15 moves beyond selection from a range of values and on to where a user actually 
types in the whole content in the different text components. 


CHAPTER 15 


Basic Text Components 


Chao: 14 explored the dynamic input selection control offered with the JSpinner ofthe 
Swing component set. In this chapter, you will look at the basic capabilities of the Swing text 
components. The more advanced text component capabilities are covered in the next chapter. 

The Swing component set features five text components. They all share a common parent 
class, JTextComponent, which defines the common behavior for all text controls. 

The direct subclasses of JTextComponent are JTextField, JTextArea, and JEditorPane. 
JTextField is used for a single line of single-attributed text (that is, a single font and a single 
color). JTextField has a single subclass, JPasswordField, for when a JTextField needs to be 
used with an input mask for the entry of a password. JTextArea is used for multiple lines of 
single-attributed text input. JEditorPane is a generic editor that can support the editing of 
multiple-attributed input. Its subclass JTextPane is customized for input in plain-text style. 

In both cases, the input can be images as well as components, in addition to text. 


Overview of the Swing Text Components 


Like all other Swing components, text components live in an MVC world. The components 
shown in Figure 15-1, which is a class hierarchy diagram, are the various available Ul delegates. 
The remaining part of the UI delegate model is the text view, which is based on the View class 
and discussed further in Chapter 16. 


Note All JTextComponent subclasses are in the javax. swing package. With the exception of 
the event-related pieces, the support interfaces and classes discussed in this chapter are found in the 
javax.swing.text package (or a subpackage). The Swing-specific, text-related event pieces are found 
in the javax.swing.event package, with remaining bits in java. awt.event and java.beans. 


The data model for each ofthe components is an implementation ofthe Document interface, of 
which there are five extensions (or implementations). The single-attributed components use 
the PlainDocument class as their data model, while the multiple-attributed components use 
DefaultStyledDocument as their model. Both of these classes subclass the AbstractDocument class, 
which defines their common Document interface implementation. The DefaultStyledDocument 
class also implements the StyledDocument interface, which is an extension of Document for 
supporting multiple-attributed content. An additional Document implementation, HTMLDocument, 
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is available for the JEditorPane when its content type is text/html. For restricting input into 
any of these documents, you can use the Document Filter class. 


JComponent 
_— 
<<Interface>> 
Scrollable JTextComponent 
A 
JTextField JTextArea JEditorPane 
JPasswordField JTextPane 


Figure 15-1. Swing text component class hierarchy diagram 


Many other classes to be discussed in this chapter and in Chapter 16 are common among 
the text components. As with many of the other Swing components, you can customize the 
look and feel of the components without creating a new Ul delegate. For the text components, 
the Highlighter, Caret, and NavigationFilter interfaces describe how text is highlighted, where 
textis inserted, and how to limit cursor positioning, respectively, thus allowing you to customize 
the text component appearance and input behavior. In addition, the InputMap/ActionMap 
classes define the bindings between keystrokes and text actions, letting you alter the feel of text 
components very easily. 

Other text component model pieces are designed for event handling. You are not limited 
to using the KeyListener/KeyEvent or TextEvent/TextListener combination for dealing with 
input validation. The Swing components also can use the DocumentEvent /DocumentListener 
combination (as well as the InputVerifier described in Chapter 2). This combination provides 
a much more flexible manner of input validation, especially in the MVC environment of the Swing 
text components. Additional event handling is done through an extension of the AbstractAction 
capabilities introduced in Chapter 2. This is the TextAction class for tying key bindings to Action 
implementations, which is discussed in detail in Chapter 16. Many of the text framework pieces are 
tied together by what is called an EditorKit, which is also discussed in Chapter 16. 


Note Due to the many interconnections among the Swing text component classes, you'll find a number of 
references in this chapter to Chapter 16. Feel free to jump between this chapter and the next to read up on 
the full details of a particular capability. 
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JTextComponent Class 


The JTextComponent class is the parent class for all the components used as textual views. It 
describes the common behavior shared by all text components. Among other things, this common 
behavior includes a Highlighter for selection support, a Caret for navigation throughout the 
content, a set of commands supported through the actions property (an array of Action imple- 
menters), a set of key bindings through a Keymap or InputMap/ActionMap combination, an 
implementation of the Scrollable interface so that each ofthe specific text components can be 
placed within a JScrol1Pane, and the text stored within the component. If that all sounds like a 
lot to manage, don't worry. This chapter will guide you through each of the pieces. 


JTextComponent Properties 


Table 15-1 shows the 27 properties of JTextComponent. These properties cover the range of 
capabilities you would expect from text components. 


Table 15-1. JTextComponent Properties 


Property Name Data Type Access 
accessibleContext AccessibleContext Read-only 
actions Action[ ] Read-only 

caret Caret Read-write bound 
caretColor Color Read-write bound 
caretListeners Caretlistener[ ] Read-only 
caretPosition int Read-write 
componentOrientation ComponentOrientation Write-only bound 
disabledTextColor Color Read-write bound 
document Document Read-write bound 
dragEnabled boolean Read-write 
editable boolean Read-write bound 
focusAccelerator char Read-write bound 
highlighter Highlighter Read-write bound 
inputMethodRequests InputMethodRequests Read-only 

keymap Keymap Read-write bound 
margin Insets Read-write bound 
navigationFilter NavigationFilter Read-write 
preferredScrollableViewportSize Dimension Read-only 
scrollableTracksVienportHeight boolean Read-only 
scrollableTracksViemportWidth boolean Read-only 
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Table 15-1. JTextComponent Properties (Continued) 


Property Name Data Type Access 
selectedText String Read-only 
selectedTextColor Color Read-write bound 
selectionColor Color Read-write bound 
selectionEnd int Read-write 
selectionStart int Read-write 

text String Read-write 

UI TextUl Read-write 


These properties can be grouped into eight basic categories: 


Data model: The document property is for the data model of all text components. The 
text property is used for treating this data model as a String. 


Color: The caretColor, disabledTextColor, selectedTextColor, and selectionColor 
properties, as well as the inherited foreground and background properties, specify the 
color for rendering the cursor, disabled text, selected text, selected text background, 
regular text, and regular text background. 


Caret: The caret, caretPosition, and navigationFilter properties are for navigating 
through the document. 


Highlighter: The highlighter, selectionStart, and selectionEnd properties are responsible 
for highlighting the selectedText section of the document. 


Margin: The margin property is for specifying how far the text contents appear from the 
edges of the text component. 


Events: The actions and keymap properties describe which capabilities the text compo- 
nent supports. In the case ofthe Action[ ] for the actions property, the capabilities are 
aseries ofActionListener implementations that you can associate with components for 
event handling. For instance, instead of creating an ActionListener to perform cut, copy, 
and paste operations, you find the appropriate Action within the actions property and 
associate it with a component. The keymap property works in a similar manner, but it 
associates Action implementations with specific keys. For instance, it contains a key 
map entry for what to do when the PageUp key is pressed. The caretListeners property 
allows you to discover the set of CaretListener objects observing the text component. 
The dragEnabled setting describes if the component supports dragging text from within 
the component. (For information about drag-and-drop support within Swing, see 
Chapter 19.) 


Scrollable interface: The properties preferredScrollableViemportSize, 
scrollableTracksViemportHeight, and scrollableTracksViemportWidth are 
implementations of the respective Scrollable interface methods. 
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+ State: The editable and focusTraversable properties describe various states of the text 
components. The editable property allows you to make a text component read-only. 
For the read-only focusTraversable property, text components are in the focus cycle 
(that is, they can be tabbed into) when they're enabled. The focusAccelerator is used 
when a neighboring JLabel has the text component set inits 1labelFor property, allowing 
you to use the visible mnemonic of the JLabel to move focus into the text component. 
The componentOrientation setting describes how the component's text will be drawn. 
Use this for languages like Hebrew where left-to-right is not necessarily the best way to 
draw characters. The JTextComponent inherits an opaque property from JComponent. 
When the opaque property is set to false, the contents ofthe area behind the text compo- 
nent bleed through, allowing you to have an image background if desired. See Figure 15-2 
for how this might appear. 


Listing 15-1 is the source code used to generate Figure 15-2. Ifyou comment out the 
setOpaque(false) line, a background image will not be shown. 


[> vacesround example TSE 


This is a test ofthe emergency broadcasdi 
system. 
Four score and seven... 
hatis going on her 
¡ c Dl 


Figure 15-2. An opaque text component with an image background 


Listing 15-1. Drawing in the Background of a Component 


import javax.swing.*; 
import java.awt.*; 


public class BackgroundSample ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() £ 
public void run() £ 

JFrame frame = new JFrame("Background Example"); 

frame.setDefaultClose0peration(JFrame.EXIT_ON CLOSE); 

final Imagelcon imagelcon = new Imagelcon("draft.gif"); 

JTextArea textArea = new JTextArea() f 
Image image = imagelcon.getImage(); 
Image grayImage = GrayFilter.createDisabledImage(image); 
[setOpaque(false);) // instance initializer 
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5 


public void paint (Graphics g) ( 
g-drawImage(grayImage, 0, O, this); 
super.paint(g); 
h 
E 
JScrollPane scrollPane = new JScrollPane(textArea); 
frame.add(scrollPane, BorderLayout.CENTER); 
frame.setSize(250, 250); 
frame.setVisible(true); 


J 


EventQueue.invokeLater(runner); 


J 
y 


JTextComponent Operations 


The JTextComponent defines the basic framework for many of the operations performed on the 
text controls. 


I/O: The public void read(Reader in, Object description) and public void 
write(Writer out) methods (both throw I0Exception) allow you to read or write 
the text component contents with ease. 


Clipboard access: The public void cut(), public void copy(), and public void paste() 
methods provide direct access to the system clipboard. 


Positioning: The public void moveCaretPosition(int position) method allows you to 
position the caret. The position represents a one-dimensional location indicating the 
number of characters to precede the caret from the beginning of the text component. 


Selection: The public void replaceSelection(String content), public void 
selectAl1(), and public void select(int selectionStart, int selectionEnd) 
methods allow you to select part of the content within the component and replace 
the content that is selected. 


Conversion: The public Rectangle modelToView(int position) throws 
BadLocationException and public int viewToModel(Point point) methods allow 
you (or, more likely, allow the system) to map a position within the JTextComponent to 
a physical mapping within the representation of the contents for the specific text UI 
delegate. 


Now that you've had an overview of the JTextComponent class, it's time to look at its 
different subclasses. First up is the JTextField, which will be used to demonstrate the operations 
just listed. 


JTextField Class 


The JTextField component is the text component for a single line ofinput. The data model 
for a JTextFieldisthe PlainDocument implementation of the Document interface. The PlainDocument 
model limits input to single-attributed text, meaning that it must be a single font and color. 
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When the Enter key is pressed within the JTextField, it automatically notifies any registered 
ActionListener implementations. 


Creating a JTextField 

There are five constructors for the JTextField component: 
public JTextField() 

JTextField textField = new JTextField(); 


public JTextField(String text) 
JTextField textField = new JTextField("Initial Text"); 


public JTextField(int columnkidth) 
JTextField textField = new JTextField(14); 


public JTextField(String text, int columnWidth) 
JTextField textField = new JTextField("Initial Text", 14); 


public JTextField(Document model, String text, int columnWidth) 
JTextField textField = new JTextField(aModel, null, 14); 


By default, you get an empty text field, zero columns wide, with a default initial model. You 
can specify the initial text for the JTextField and how wide you want the component to be. 
Width is specified as the number of m characters in the current font that will fit within the 
component. There's no restriction on the number of characters that can be input. Ifyou specify 
the Document data model in the constructor, you will probably want to specify a null initial-text 
argument. Otherwise, the current contents of the document will be replaced by the initial text for 
the text field. 


Using JLabel Mnemonics 


In the discussion of mnemonics in Chapter 4, you learned that the various button classes can 
have a keyboard shortcut that causes the button component to be selected. The special mnemonic 
character is usually underlined to indicate this visually. Ifthe user presses the mnemonic character, 
along with a platform-specific mnemonic activation key, such as Alt for both Windows and 
UNIX, the button is activated /selected. You can provide a similar capability for a JTextField, 
and all other text components, with the help ofa JLabel. 

You can set the display mnemonic for a label, but instead of selecting the label when the 
mnemonic key is pressed, selection causes an associated component to get the input focus. 
The display mnemonic is set with the public void setDisplayedMnemonic(character) method, 
in which character is either an int or a char. Using the KeyEvent constants when changing the 
mnemonic setting simplifies initialization considerably. 

The following source demonstrates how to interconnect a specific JLabel and JTextField. 


JLabel label = new JLabel("Name: "); 
label.setDisplayedMnemonic(KeyEvent.VK_N); 
JTextField textField = new JTextField(); 
label.setlLabelFor(textField); 
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In addition to calling the setDisplayedMnemonic() method, you must also call the public 
void setLabelFor(Component component) method of JLabel. This configures the JLabel to 
move input focus to the text field when the special mnemonic value is pressed. 

Figure 15-3 shows what this sample program might look like. The complete source for the 
program follows in Listing 15-2. 


[> tobetrocus example TES 


Name: [Pressing ALT-N moves focus here 


Somewhere Else 


Figure 15-3. Connecting a JLabel and a JTextField 


Listing 15-2. Connected JLabel and JTextField 


import javax.swing.*; 
import java.awt.*; 
import java.awt.event.*; 


public class LabelSample ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() £ 
JFrame frame = new JFrame("Label Focus Example"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
JPanel panel = new JPanel(new BorderLayout()); 
JLabel label = new JLabel("Name: "); 
label.setDisplayedMnemonic(KeyEvent.VK_N); 
JTextField textField = new JTextField(); 
label.setlLabelFor(textField); 
panel.add(label, BorderLayout.WEST); 
panel.add(textField, BorderLayout.CENTER); 
frame.add(panel, BorderLayout.NORTH); 
frame.add(new JButton("Somewhere Else"), BorderLayout.SOUTH) ; 
frame.setSize(250, 150); 
frame.setVisible(true); 
y 
5 
EventQueue.invokeLater(runner); 
J 
) 


JTextField Properties 
Table 15-2 lists the 14 properties of JTextField. 


Table 15-2. JTextField Properties 
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Property Name Data Type Access 
accessibleContext AccessibleContext Read-only 
actionCommand String Write-only 

action Action Read-write bound 
actionListeners ActionListener[ ] Read-only 
actions Action[ ] Read-only 
columns int Read-write 
document Document Write-only bound 
font Font Write-only 
horizontalAlignment int Read-write bound 
horizontalVisibility BoundedRangeModel Read-only 
preferredSize Dimension Read-only 
scrollOffset int Read-write 
UlClassID String Read-only 
validateRoot boolean Read-only 


There's a tight coupling between the horizontalVisibility and scroll0ffset properties. 
The BoundedRangeModel for the horizontalVisibility property of JTextField represents the 
width range required for displaying the contents of the text field. Ifthere isn't enough space to 
display the contents, the scro110Ffset setting reflects how far offto the left the text has scrolled. As 
the user navigates through the text within the JTextField, the scrol10ffset value is automati- 
cally updated. For example, the text field in Figure 15-4 contains the 26 letters of the alphabet 
plus the 10 cardinal numbers: ABCDEFGHIJKLMNOPQRSTUVWXYZ 1234567890. Not all these 
characters fit in the field; therefore, the letters A through J have scrolled off to the left. 


E 


Name: KLMNOPORSTUWWYZ1 234567890] 


Figure 15-4. The scrollOffset property reflects how far to the left the field's contents have scrolled; 
here, it is not at zero, so the beginning contents (A-J) have scrolled off to the left. 
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By changing the scrol10ffset setting, you can control which part of the text field is visible. 
To ensure that the beginning of the contents for the text field is visible, set the scrol10ffset 
setting to zero. To make sure that the end of the contents is visible, you need to ask the 
horizontalVisibility property what the extent of the BoundedRangeModel is, to determine the 
width of the range, and then set the scro110ffset setting to the extent setting, as follows: 


BoundedRangeModel model = textField.getHorizontalVisibility(); 
int extent = model.getExtent(); 
textField.setScroll0ffset(extent); 


By changing the horizontalAlignment property setting, you can right-, left-, or center-justify 
the contents of a JTextField. By default, the text alignment is left-justified. The public void 
setHorizontalAlignment(int alignment) method takes an argument of JTextField. LEFT, 
JTextField.CENTER, JTextField.RIGHT, JTextField. LEADING (the default), or JTextField.TRAILING 
to specify the contents alignment. Figure 15-5 shows how the alignment setting affects the 
contents. 


[o argrmentecample TSE 


Left 


_Center _ 
Right 


Leading 


Trailing 


Figure 15-5. Text field alignments 


Note You can set the document property, inherited from JTextComponent, to any implementation of the 
Document interface. If you use a StyledDocument with a JTextField, the Ul delegate will ignore all style 
attributes. The StyledDocument interface is discussed in Chapter 16. 


JTextComponent Operations with a JTextField 


Have you ever looked for an easy way to load or save the contents of a text component? The 
Swing text components provide such a method. Additionally, the Swing text components have 
built-in support to access the system clipboard for cut, copy, and paste operations. These oper- 
ations are possible with all JTextComponent subclasses. They're shown here specifically for the 
JTextField because they need a specific implementation to be truly demonstrated. You can 
perform the same tasks with the JPasswordField, JTextArea, JEditorPane, and JTextPane. 


Loading and Saving Content 


With the public void read(Reader in, Object description) and public void write(Writer 
out) methods from JTextComponent (both throw an IOException), you can easily load and save 
the contents from any text component. With the read() method, the description argument is 
added as a property of the Document data model. This allows you to retain information about 
where the data came from. The following example demonstrates how to read in the contents of 
file name and store itin textComponent. The file name is automatically retained as the description. 
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FileReader reader = null; 
try ( 
reader = new FileReader(filename); 
textComponent.read(reader, filename); 
) catch (IOException exception) ( 
System.err.println("Load oops"); 
Y finally ( 
if (reader != null) € 
try ( 
reader.close(); 
$ catch (IOException exception) ( 
System.err.println("Error closing reader"); 
exception.printStackTrace(); 
) 
) 
J 


If you later wanted to get the description back from the data model, which happens to be 
the file name in this case, you would just ask, like this: 


Document document = textComponent.getDocument(); 
String filename = (String)document.getProperty(Document.StreamDescriptionProperty); 


The properties of the Document are simply another key/value lookup table. The key in this 
particular case is the class constant Document. StreamDescriptionProperty. Ifyou don't want a 
description stored, you pass null as the description argument to the read() method. (The 
Document interface will be discussed in more detail later in this chapter.) 

Before you can read a file into a text component, you need to create the file to read. This 
could be done outside a Java program, or you could use the write() method of JTextComponent 
to create the file. The following demonstrates how to use the write() method to write the 
contents. For simplicity's sake, it doesn't deal with getting the file name from the Document, 
because this would not be set initially. 


FileWriter writer = null; 
try ( 
writer = new FileWriter(filename); 
textComponent .write(writer); 
) catch (IOException exception) ( 
System.err.println("Save oops"); 
) finally ( 
if (writer != null) € 
try ( 
writer.close(); 
$ catch (IOException exception) ( 
System.err.println("Error closing writer"); 
exception.printStackTrace(); 
h 
) 
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Figure 15-6 shows a sample program that uses the loading and saving capabilities, with 
these options implemented through buttons (although Load and Save options are more 
commonly seen under a File menu). The Clear button clears the contents of the text field. 


Hello, Worlal 


Figure 15-6. Loading and saving a text component 


The source in Listing 15-3 puts all the pieces together in a sample program to demonstrate 
loading and saving streams. 


Listing 15-3. Loading and Saving Streams with a JTextComponent 


import java.awt.*; 

import java.awt.event.*; 
import javax.swing.*; 
import javax.swing.text.*; 
import java.io.*; 


public class LoadSave ( 


public static void main (String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
final String filename = "text.out"; 
JFrame frame = new JFrame("Loading/Saving Example"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


final JTextField textField = new JTextField(); 
frame.add(textField, BorderLayout.NORTH); 


JPanel panel = new JPanel(); 


// Setup actions 
Action loadAction = new AbstractAction() ( 
( 
putValue(Action.NAME, "Load"); 
) 
public void actionPerformed(ActionEvent e) ( 
doLoadCommand(textField, filename); 
) 
y; 
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JButton loadButton = new JButton (loadAction); 
panel.add(loadButton); 


Action saveAction = new AbstractAction() f 
Í 
putValue(Action.NAME, "Save"); 
) 
public void actionPerformed(ActionEvent e) ( 
doSaveCommand(textField, filename); 
) 
$»; 
JButton saveButton = new JButton (saveAction); 
panel.add(saveButton); 


Action clearAction = new AbstractAction() f 
Í 
putValue(Action.NAME, "Clear"); 
) 
public void actionPerformed(ActionEvent e) ( 
textField.setText(""); 
) 
$»; 
JButton clearButton = new JButton (clearAction); 
panel.add(clearButton); 


frame.add(panel, BorderLayout. SOUTH); 


frame.setSize(250, 150); 
frame.setVisible(true); 


EventQueue.invokeLater(runner); 


public static void doSaveCommand(JTextComponent textComponent, 


String filename) ( 


FileWriter writer = null; 
try ( 


writer = new FileWriter(filename); 
textComponent .write(writer); 


$ catch (IOException exception) ( 


System.err.println("Save oops"); 
exception.printStackTrace(); 


$ finally £ 


if (writer !l= null) £ 


try [ 
writer.close(); 
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y catch (IOException exception) ( 
System.err.println("Error closing writer”); 
exception.printStackTrace(); 

y 

J 
J 
J 


public static void doLoadCommand(JTextComponent textComponent, 
String filename) ( 

FileReader reader = null; 

try ( 
reader = new FileReader(filename) ; 
textComponent.read(reader, filename); 

) catch (IOException exception) ( 
System.err.println("Load oops"); 
exception.printStackTrace(); 

) finally ( 
if (reader != null) £ 

try ( 
reader.close(); 

) catch (IOException exception) ( 
System.err.println("Error closing reader”); 
exception.printStackTrace(); 


Note By default, file reading and writing deals only with plain text. If the contents of a text component are 
styled, the styled attributes aren't saved. The EditorKit class can customize this loading and saving behavior. 


You'll explore that class in Chapter 16. 


Accessing the Clipboard 


To use the system clipboard for cut, copy, and paste operations, you do not need to manually 

concoct a Transferable clipboard object. Instead, you just call one of these three methods of 

the JTextComponent class: public void cut(), public void copy(), or public void paste() 
You could call these methods directly from ActionListener implementations associated 


with buttons or menu items, as in the following: 
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ActionListener cutListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
aTextComponent.cut(); 
) 
5 


However, there is an easier way that doesn't require you to manually create the 
ActionListener implementations. This method involves finding an existing cut action by 
asking the text component. Ifyou look at the set of JTextComponent properties in Table 15-1, 
you'll notice one property named actions, which is an array of Action objects. This property 
contains a predefined set of Action implementations that you can directly associate as an 
ActionListener with any button or menu item. Once you get the current actions for the text 
component, you can go through the array until you find the appropriate one. Because actions 
are named, you merely need to know the text string for the name. The DefaultEditorKit class 
has about 40 keys as public constants. Here is an example of getting the cut action: 


Action actions[] = textField.getActions(); 
Action cutAction = TextUtilities.findAction(actions, DefaultEditorKit.cutAction); 


All actions in the set for a text component are a type of TextAction, which is an extension 
ofthe AbstractAction class. The essential thingto know about a TextAction is thatit acts on the 
last focused text component. (The TextAction class, along with the DefaultEditorKit, will be 
discussed more extensively in Chapter 16.) So, even though the preceding source fragment 
acquires the cut action from a text field, the same cut action would work for another text 
component on the same screen. Whichever text component had the input focus last would be 
the one cut when the specific cutAction is activated. 

To help you visualize this behavior, Figure 15-7 shows a screen with a JTextField at the 
top, a JTextArea in the middle, and buttons on the bottom for the cut, copy, and paste opera- 
tions (although these operations are more commonly available through an Edit menu). Ifyou 
run the program, you'll notice that the cut, copy, and paste actions act on the last focused text 
component. 
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Figure 15-7. Accessing the system clipboard from a text component 


The source code in Listing 15-4 is the complete example for finding an Action in the 
actions property array and using cut, copy, and paste. 
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Listing 15-4. Accessing the System Clipboard 


import java.awt.*; 

import java.awt.event.*; 
import java.util.*; 

import javax.swing.*; 
import javax.swing.text.*; 


public class CutPasteSample ( 
public static void main (String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("Cut/Paste Example"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


JTextField textField = new JTextField(); 
JTextArea textArea = new JTextArea(); 
JScrollPane scrollPane = new JScrollPane(textArea); 


frame.add(textField, BorderLayout.NORTH); 
frame.add(scrollPane, BorderLayout.CENTER); 


Action actions[ ] 


textField.getActions(); 


Action cutAction 

TextUtilities.findAction(actions, DefaultEditorKit.cutAction); 
Action copyAction = 

TextUtilities.findAction(actions, DefaultEditorKit.copyAction); 
Action pasteAction = 

TextUtilities.findAction(actions, DefaultEditorKit.pasteAction); 


JPanel panel = new JPanel(); 
frame.add(panel, BorderLayout.SOUTH); 


JButton cutButton = new JButton(cutAction); 
cutButton.setText("Cut"); 
panel.add(cutButton); 


JButton copyButton = new JButton(copyAction); 
copyButton.setText("Copy"); 
panel .add(copyButton); 


JButton pasteButton = new JButton(pasteAction); 
pasteButton.setText("Paste"); 
panel .add(pasteButton); 
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frame.setSize(250, 250); 
frame.setVisible(true); 
J 
5 
EventQueue.invokeLater(runner); 
y 
) 


The example in Listing 15-4 uses the TextUtilities support class shown in Listing 15-5. 
There's no direct way to find out if a specific action for a specific key exists in the actions 
property array. Instead, you must manually search for it. The public static Action 
findAction(Action actions[], String key) method does the searching for you. 


Listing 15-5. TextUtilities Support Class 


import javax.swing.*; 
import javax.swing.text.*; 
import java.util.Hashtable; 


public final class TextUtilities ( 
private TextUtilities() ( 
J 


public static Action findAction(Action actions[], String key) ( 
Hashtable<0bject, Action> commands = new Hashtable<0bject, Action>(); 
for (int i = 0; i < actions.length; i++) ( 
Action action = actions[i]; 
commands . put (action.getValue(Action.NAME), action); 
) 
return commands.get(key); 
) 
) 


Note For security reasons, the cut () and copy() methods of the JPasswordField class do not place 
the current contents onto the system clipboard (the system will beep instead). You can still paste() some- 
thing from the clipboard into a JPasswordField, though. 


Document Interface 


The Document interface defines the data model for the different text components. Implementa- 
tions of the interface are meant to store both the actual content as well as any information to 
mark up the content (with bold, italics, or color). While all the content will be text, the way in 
which the text component displays the content could result in nontextual output, such as an 
HTML renderer. 
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The data model is stored apart from the text component (the view). Therefore, if you're 
interested in monitoring changes to the content of a text component, you must watch the 
Document itself, not the text component, for changes. Ifthe changes reach the text component, 
it's too late—the model has already changed. To listen for changes, attach a DocumentListener 
to the model. However, the more likely scenario for restricting input is to provide a custom 
model or attach a DocumentFilter to the AbstractDocument. You can also attach an InputVerifier 
to the text component. However, that wouldn't be used until the input focus tried to leave the 
component. 


Note In addition to accessing the textual content through the Document interface, a framework is defined 
to support undo/redo capabilities. This will be explored in Chapter 21. 


Now, let's look at the pieces that make up a Document. First, here's the base interface definition: 


public interface Document ( 
// Constants 
public final static String StreamDescriptionProperty; 
public final static String TitleProperty; 
// Listeners 
public void addDocumentListener(DocumentListener listener); 
public void removeDocumentListener(DocumentListener listener); 
public void addUndoableEditListener(UndoableEditListener listener); 
public void removeUndoableEditListener(UndoableEditListener listener); 
// Properties 
public Element getDefaultRootElement(); 
public Position getEndPosition(); 
public int getlength(); 
public Element[ ] getRootElements(); 
public Position getStartPosition(); 
// Other methods 
public Position createPosition(int offset) throws BadLocationException; 
public Object getProperty(Object key); 
public String getText(int offset, int length) throws BadLocationException; 
public void getText(int offset, int length, Segment txt) 
throws BadLocationException; 
public void insertString(int offset, String str, AttributeSet a) 
throws BadLocationException; 
public void putProperty(Object key, Object value); 
public void remove(int offset, int len) throws BadLocationException; 
public void render(Runnable r); 


The content within a Document is described by a series of elements in which each element 
implements the Element interface. Within each element, you can store attributes so that select 


CHAPTER 15 BASIC TEXT COMPONENTS 539 


content can be made bold, italic, or colorized. The elements don't store the content; they just 

hold the attributes. Therefore, one Document can be rendered differently from different Element sets. 
The following is an example of a basic HTML document with a title and a bulleted list 

for content. 


<html> 


<head> 
<title>Cards</title> 
</head> 


<body> 
<h1>Suits:</h1> 


<ul> 

li>Clubs</1i> 
li>Diamonds</1i> 
li>Hearts</li> 
li>Spades</li> 


Looking at the structure of the elements in this HTML document, you get a hierarchy as 
shown in Figure 15-8. 


HEAD BODY 


Figure 15-8. Examining the element makeup of a document 
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Although this particular document might not warrant it, multiple element hierarchies are 
possible. Each would store different attributes because a particular text component could have 
an alternative rendering of the content. Alternatively, different style sheets could be used to 
render the same HTML markup differently. 


AbstractDocument Class 


The AbstractDocument class provides the basic implementation of the Document interface. It 
defines the management of the listener lists, provides a read-write locking mechanism to 
ensure that content isn't corrupted, and enables a Dictionary for storing document properties. 

Table 15-3 lists the 11 properties of the AbstractDocument class, of which 5 are defined by 
the Document interface itself. 


Table 15-3. AbstractDocument Properties 


Property Name Data Type Access 

asynchronousLoadPriority* int Read-write 
bidiRootElement* Element Read-only 
defaultRootElement Element Read-only 
documentFilter* DocumentFilter Read-write 
documentListeners* DocumentListener[ ] Read-only 
documentProperties* Dictionary Read-write 
endPosition Position Read-only 
length int Read-only 
rootElements Element[ ] Read-only 
startPosition Position Read-only 
undoableEditListeners* UndoableEditListener[ ] Read-only 


* These properties are specific to the AbstractDocument class. The remaining five properties are defined in the 
Document interface. 


For the most part, you don't access any of these properties directly, except perhaps 
documentFilter. In the case ofthe documentProperties property, you get and set individual prop- 
erties with the public Object getProperty(Object key) and public void putProperty(Object key, 
Object value) methods. For the length property, in most cases, you can simply ask for the text 
within a text component, and then get ¡ts length by using textComponent .getText().length(). 

The bidiRootElement property is for the bidirectional root element, which may be appro- 
priate in certain Unicode character sets. You would normally just use the defaultRootElement. 
However, both are rarely accessed. 
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PlainDocument Class 


The PlainDocument class is a specific implementation ofthe AbstractDocument class. It does not 
store any character-level attributes for the content. Instead, the elements describe where the 
content and each line in the content begin. 

The program in Listing 15-6 walks through the Element tree for a PlainDocument, the model 
used for both the JTextField and the JTextArea. 


Listing 15-6. Element Walker 


import java.awt.*; 

import java.awt.event.*; 
import java.util.*; 
import javax.swing.*; 
import javax.swing.text.*; 


public class ElementSample ( 
public static void main (String args[]) ( 
Runnable runner = new Runnable() 4 
public void run() £ 
JFrame frame = new JFrame("Element Example”); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


final JTextArea textArea = new JTextArea(); 
JScrollPane scrollPane = new JScrollPane(textArea); 


JButton button = new JButton("Show Elements"); 
ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
Document document = textArea.getDocument(); 
ElementIterator iterator = new ElementIterator(document); 
Element element = iterator.first(); 
while (element != null) £ 
System.out.println(element.getStartOffset()); 
element = iterator.next(); 
) 
A 
5 


button.addActionListener(actionListener); 


frame.add(scrollPane, BorderLayout.CENTER); 
frame.add(button, BorderLayout. SOUTH); 


frame.setSize(250, 250); 
frame.setVisible(true); 
J 
5 
EventQueue.invokeLater(runner); 
) 
y 
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Assume the contents of the JTextArea are as follows: 


Hello, World 
Welcome Home 
Adios 


The program would report Element objects starting at 0, O, 13, and 26. The first 0 represents 
the start of the content; the second represents the start of the first line. 
You'll learn more about Element in Chapter 16. 


Filtering Document Models 


In the AWT world, if you want to restrict input into a text field —such as to limit input to alpha- 
numeric characters or to some numeric range of values—you attach a KeyListener and consume() 
keystrokes that you don't want to appear within the component. With the Swing text components, 
you could either create a new Document implementation and customize what's accepted in the 
Document or attach a DocumentFilter and let it filter input. 

While you can certainly create a custom subclass of Document, the more object-oriented 
approach is to create a filter, as you don't want to change the Document; you just want to limit 
the input into the model. You then attach the newly created filter to the document by calling 
the setDocumentFilter() method of AbstractDocument. Filters work with both PlainDocument 
and StyledDocument subclasses. 

DocumentFilter is a class, not an interface, so you must create a subclass of that to filter the 
text into the document of a text component. If you create a subclass of DocumentFilter, over- 
riding these three methods allows you to customize input: 


+ public void insertString(DocumentFilter.FilterBypass fb, int offset, String 
string, AttributeSet attributes): Called when a text string is inserted into the Document. 


+ public void remove(DocumentFilter.FilterBypass fb, int offset, int length): 
Called when something is deleted. 


+ public void replace(DocumentFilter.FilterBypass fb, int offset, int length, 
String text, AttributeSet attrs): Called when something is inserted into the 
currently selected text. 


To restrict input, just override each method and check to see ifthe new content would be 
valid. Ifthe content would not be valid, reject it. 

For example, to create a DocumentFilter subclass to limit to a numeric range, you need to 
override the behavior of insertString(), remove(), and replace(). Because you're ensuring 
that the input is numeric and within a valid range, you must validate the proposed input to see 
ifit's acceptable. Ifit is acceptable, then you can modify the document model by calling the 
insertString(), remove(), or replace() method of the DocumentFilter.FilterBypass argument of 
each original method call. When the inputis unacceptable, you throw a BadLocationException. 
Seeing this exception thrown ensures the input method framework understands the user input 
was invalid. This will typically trigger the system to beep. Listing 15-7 shows a custom document 
filter for limiting an integer range. 
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Listing 15-7. Custom Document Filter 


import javax.swing.text.*; 
import java.awt.Toolkit; 


public class IntegerRangeDocumentFilter extends DocumentFilter ( 


int minimum, maximum; 
int currentValue = 0; 


public IntegerRangeDocumentFilter(int minimum, int maximum) ( 
this.minimum = minimum; 
this.maximum = maximum; 


J 


public void insertString(DocumentFilter.FilterBypass fb, int offset, 
String string, AttributeSet attr) throws BadLocationException ( 


if (string == null) ( 
return; 
j else £ 
String newValue; 
Document doc = fb.getDocument(); 
int length = doc.getLength(); 
if (length == 0) [ 
newValue = string; 
y else [ 
String currentContent = doc.getText(0, length); 
StringBuffer currentBuffer = new StringBuffer(currentContent); 
currentBuffer.insert(offset, string); 
newValue = currentBuffer.toString(); 
) 
currentValue = checkInput(newValue, offset); 
fb.insertString(offset, string, attr); 
) 
) 


public void remove(DocumentFilter.FilterBypass fb, int offset, int length) 
throws BadLocationException ( 


Document doc = fb.getDocument(); 

int currentLength = doc.getLength(); 

String currentContent = doc.getText(O, currentLength); 

String before = currentContent.substring(0, offset); 

String after = currentContent.substring(length+offset, currentLength); 
String newValue = before + after; 

currentValue = checkInput(newValue, offset); 

fb.remove(offset, length); 
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public void replace(DocumentFilter.FilterBypass fb, int offset, int length, 
String text, AttributeSet attrs) throws BadlLocationException Í 


Document doc = fb.getDocument(); 

int currentLength = doc.getLength(); 

String currentContent = doc.getText(0, currentLength); 

String before = currentContent.substring(0, offset); 

String after = currentContent.substring(length+offset, currentLength); 
String newValue = before + (text == null ? "" : text) + after; 
currentValue = checkInput(newValue, offset); 

fb.replace(offset, length, text, attrs); 


J 


private int checkInput(String proposedValue, int offset) 
throws BadLocationException ( 
int newValue = 0; 
if (proposedValue.length() > 0) £ 
try ( 
newValue = Integer.parselInt(proposedValue); 
$ catch (NumberFormatException e) ( 
throw new BadLocationException(proposedValue, offset); 
J 
J 


if ((minimum <= newValue) 88 (newValue <= maximum)) 4 
return newValue; 


y else £ 
throw new BadLocationException(proposedValue, offset); 
J 
J 

J 
Figure 15-9 shows the numeric range filter in use. 

lol 

Range: 0-255 34 


Range: -100-100 É 
Range: 1000-2000 11000 


Figure 15-9. Using a Document that restricts input to a range of values 


The sample program using the new IntegerRangeDocumentFilter follows in Listing 15-8. 
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Listing 15-8. Program Using a Custom Document Filter 


import javax.swing.*; 
import javax.swing.text.*; 
import java.awt.*; 

import java.awt.event.*; 


public class RangeSample ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() £ 
public void run() £ 
JFrame frame = new JFrame("Range Example"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
frame.setLayout(new GridLayout(3, 2)); 


frame.add(new JLabel("Range: 0-255")); 

JTextField textFieldOne = new JTextField(); 

Document textDocOne = textFieldOne.getDocument (>); 

DocumentFilter filterO0ne = new IntegerRangeDocumentFilter(0, 255); 
((AbstractDocument)textDocOne).setDocumentFilter(FfilterOne); 
frame.add(textFieldOne) ; 


frame.add(new JLabel("Range: -100-100")); 

JTextField textFieldTwo = new JTextField(); 

Document textDocTwo = textFieldTwo.getDocument (); 

DocumentFilter filterTwo = new IntegerRangeDocumentFilter(-100, 100); 
((AbstractDocument)textDocTwo).setDocumentFilter(filterTwo); 
frame.add(textFieldTwo) ; 


frame.add(new JLabel("Range: 1000-2000")); 

JTextField textFieldThree = new JTextField(); 

Document textDocThree = textFieldThree.getDocument (); 

DocumentFilter filterThree = new IntegerRangeDocumentFilter(1000, 2000); 
((AbstractDocument)textDocThree).setDocumentFilter(filterThree); 
frame.add(textFieldThree); 


frame.setSize(250, 150); 
frame.setVisible(true); 
) 
5 
EventQueue.invokeLater(runner); 
y 
J 


If you try out this program, you”!l notice a couple of interesting issues. The first text field, 
with a range of 0 to 255, works fine. You can enter and delete characters at will, as long as the 
content is within the range. 
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In the second text field, the valid range is -100 to +100. Although you can enter any of the 
201 numbers into the text field, if you want a negative number, you need to enter something 
like 3, left arrow, and minus sign (-). Because the text field validates input with each key, the - by 
itself isn't valid. You would need to either specifically accept a - as valid input in the checkInput() 
method of the custom DocumentFilter or force users to enter negative numbers in an awkward 
manner. 

The third text field presents an even more troublesome situation. The valid range of input 
is 1000-2000. As you press each key to enter a number, such as 1500, it's rejected. You can't 
build up the input to 1500 because, by themselves, 1, 5, and 0 are not valid input. Instead, to 
enter a number into this text field, you must enter it somewhere else, place it into the system 
clipboard, and then use Ctrl-V to paste itinto the text field as the field”s final value. You can't 
use Backspace to correct a mistake, because no three-digit numbers are valid. 

While the IntegerRangeDocumentFilter class shown in Listing 15-7 presents a workable 
DocumentFilter for any integer range, it works best with ranges of positive numbers that begin 
at zero. If you don't mind seeing the temporarily invalid input in the fields, it may be better to 
just attach an InputVerifier to deal with validation when leaving the text field. 


DocumentlListener and DocumentEvent Interfaces 


If you're interested in finding out when the content of a text component changes, you can 
attach an implementation of the DocumentListener interface to the Document model of the 
component. 


public interface DocumentListener implements EventListener ( 
public void changedUpdate(DocumentEvent documentEvent); 
public void insertUpdate(DocumentEvent documentEvent); 
public void removeUpdate(DocumentEvent documentEvent); 


J 


From the three interface methods, you can find out if the contents were added to 
(insertUpdate()), removed (removeUpdate()), or stylistically changed (changedUpdate()). 
Notice that the latter is an attribute change versus a content change. 

The interface method will receive an instance of DocumentEvent, from which you can find 
out where the change occurred, as well as the type of change, as follows: 


public interface DocumentEvent ( 
public Document getDocument(); 
public int getLength(); 
public int getOffset(); 
public DocumentEvent.EventType getType(); 
public DocumentEvent.ElementChange getChange(Element element); 


The offset property of the event is where the change started. The length property of 
the event tells the length of the change that happened. The type of the event can be derived 
from whichever one of the three DocumentListener methods were called. In addition, the 
DocumentEvent .EventType class has three constants—CHANGE, INSERT, and REMOVE—s0 you 
can find out which event type happened directly from the type property. 
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The getChange() method of DocumentEvent requires an Element to return a 
DocumentEvent .ElementChange. You normally use the default root element from the 
Document, as in the following example. 


Document documentSource = documentEvent.getDocument (); 
Element rootElement = documentSource.getDefaultRootElement(); 
DocumentEvent.ElementChange change = documentEvent.getChange(rootElement); 


Once you have your DocumentEvent . ElementChange instance, you can find out the added 
and removed elements, if you need that level ofinformation. 


public interface DocumentEvent.ElementChange ( 
public Element[ ] getChildrenAdded(); 
public Element[ ] getChildrenRemoved(); 
public Element getElement(); 
public int getIndex(); 

J 


Caret and Highlighter Interfaces 


Now that you understand the data model aspect of a text component, you can look at some 
aspects ofits selection rendering through the Caret and Highlighter interfaces. Remember 
that these are properties of the text component, not the data model. 

The Caret interface describes what's usually referred to as the cursor: the location in the 
document where you can insert text. The Highlighter interface provides the basis for how to 
paint selected text. These two interfaces, their related interfaces, and their implementations 
are rarely altered. The text components simply use their default implementations with the 
DefaultCaret and DefaultHighlighter classes. 

Although you probably won't alter the caret and highlighter behavior for a text component, 
you should know that there are many interrelated classes working together. For the Highlighter 
interface, the predefined implementation is called DefaultHighlighter, which extends another 
implementation called LayeredHighlighter. The Highlighter also manages a collection of 
Highlighter.Highlight objects to designate highlighted sections. 

The DefaultHighlighter creates a DefaultHighlighter.HighlightPainter to paint 
the highlighted section(s) of text. The HighlightPainter is an implementation of the 
Highlighter.HighlightPainter interface and extends the LayeredHighlighter.LayerPainter 
class. Each section to paint is described by a Highlighter.Highlight, where the Highlighter 
manages the set. The actual HighlightPainter is created by the DefaultCaret implementation. 

The Highlighter interface describes how to paint selected text within a text component. If 
you don't like the color, you can simply change the TextField.selectionBackground Ul property 
setting to a different color. 


public interface Highlighter ( 
// Properties 
public Highlighter.Highlight[ ] getHighlights(); 
// Other methods 
public Object addHighlight(int po, int p1, Highlighter.HighlightPainter p) 
throws BadLocationException; 
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public void changeHighlight(Object tag, int po, int p1) 
throws BadLocationException; 

public void deinstal1(JTextComponent component); 

public void install(JTextComponent component) 

public void paint(Graphics g); 

public void removeA11Highlights(); 

public void removeHighlight(Object tag); 


The Caret interface describes the current cursor, as well as several selection attributes. Of 
the Highlighter and Caret interfaces, the latter is the one that you would actually use, although 
itisn't necessary to subclass it. 


public interface Caret ( 
// Properties 
public int getBlinkRate(); 
public void setBlinkRate(int newValue); 
public int getDot(); 
public void setDot(int newValue); 
public Point getMagicCaretPosition(); 
public void setMagicCaretPosition(Point newValue); 
public int getMark(); 
public boolean isSelectionVisible(); 
public void setSelectionVisible(boolean newValue); 
public boolean isVisible(); 
public void setVisible(boolean newValue); 
// Listeners 
public void addChangeListener(ChangeListener 1); 
public void removeChangelistener(ChangeListener 1); 
// Other methods 
public void deinstall(JTextComponent c); 
public void install(JTextComponent c); 
public void moveDot(int dot); 
public void paint(Graphics g); 


Table 15-4 lists the six attributes of Caret. 


Table 15-4. Caret Properties 


Property Name Data Type Access 

blinkRate int Read-write 
dot int Read-write 
magicCaretPosition Point Read-write 
mark int Read-only 
selectionVisible boolean Read-write 


visible boolean Read-write 
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The blinkRate is the millisecond delay between the flashes of the caret. The dot property 
is the current position within the text component ofthe cursor. To move the cursor to another 
position so that some text will be highlighted, add a call to the moveDot (int newPosition) 
method. This sets the mark property to the old dot position and sets the new dot setting to the 
new position. 

The magicCaretPosition property deals with moving up and down lines of different 
lengths. For example, suppose the following three lines of text were on your screen: 


Friz Freleng 
Mel Blanc 
What's up Doc? 


Now suppose that the current cursor position is between the n and g on the first line. Ifyou 
pressed the down arrow twice, you would want the cursor to stay at the same horizontal posi- 
tion, instead of moving to the end of the shorter second line. It's the magicCursorPosition 
property that retains this information, so that the cursor ends up being between the D and the 
o in the third line. Without the magic position retained, the cursor would fall in between the p 
and the word space of the last line. 

One useful instance of using the caret is to find the current screen location in response to 
a keystroke. That way, you can pop up a menu at the current cursor position. This would be 
similar to the Code Insights option in JBuilder or IntelliSense in Visual Studio, in which the 
tool helps you complete method calls by popping up a menu of methods. Given the current 
dot location in the model, map it to the position in the view with the public Rectangle 
modelToView(int position) method of JTextComponent (which can throw a BadLocationException). 
Then use the Rectangle returned as the location to pop up the menu, as shown in Figure 15-10. 


101 
[This is atesil Option 1 
Option 2 


Figure 15-10. Using the Caret to determine a pop-up location 


The program in Listing 15-9 will show a JPopupMenu at the location where the period (.) key 
is pressed in the text field. 


Listing 15-9. Mapping Caret Location to Pop-Up Position 


import javax.swing.*; 
import javax.swing.text.*; 
import javax.swing.plaf.*; 
import java.awt.*; 

import java.awt.event.*; 
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public class PopupSample ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("Popup Example”); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


final JPopupMenu popup = new JPopupMenu(); 
JMenultem menultem1 = new JMenultem("Option 1"); 
popup.add(menuTtem1); 


JMenultem menultem2 = new JMenultem("Option 2"); 
popup.add(menultem2); 


final JTextField textField = new JTextField(); 
frame.add(textField, BorderLayout.NORTH); 


ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
try ( 
int dotPosition = textField.getCaretPosition(); 
Rectangle popuplLocation = textField.modelToView(dotPosition); 
popup.show(textField, popuplocation.x, popuplLocation.y); 
) catch (BadLocationException badLocationException) ( 
System.err.println("0ops"); 
) 
) 
5 
KeyStroke keystroke = 
KeyStroke.getKeyStroke(KeyEvent.VK_PERIOD, O, false); 
textField.registerKeyboardAction(actionlistener, keystroke, 
JComponent .WNHEN_FOCUSED) ; 


frame.setSize(250, 150); 
frame.setVisible(true); 
) 
5 
Event0Queue.invokeLater(runner); 
J 
y 


CaretListener Interface and CaretEvent Class 


You can listen for cursor movements in two ways: associate a ChangeListener with the Caret or 
associate a CaretListener with the JTextComponent. Working directly with the JTextComponent 
is the easier approach, though both will function equally well. 
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In the case of the CaretListener, there's a single method defined by the interface: 


public interface CaretListener implements EventListener ( 
public void caretUpdate (CaretEvent caretEvent); 


) 


When the listener is notified, a CaretEvent is sent, which reports on the new dot and mark 
locations. 


public abstract class CaretEvent extends EventObject ( 
public CaretEvent(Object source); 
public abstract int getDot(); 
public abstract int getMark(); 


) 


To demonstrate, Figure 15-11 shows a program with a CaretListener attached to the inner 
JTextArea. When the CaretEvent happens, the current dot value is sent to the top text field and 
the current mark setting is sent to the button. In the example, the cursor dotis at the beginning 
of the second line, with the mark at the end. 


[> corertramne TES 


Dot: 13 


Friz Freleng 
el Blanc 
Whats up Doc? 


Figure 15-11. CaretListener sample 
Listing 15-10 shows the source associated with the example in Figure 15-11. 


Listing 15-10. Listening for Caret Changes 


import javax.swing.*; 
import javax.swing.event.*; 
import java.awt.*; 


public class CaretSample ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() £ 
public void run() £ 
JFrame frame = new JFrame("Caret Example"); 
frame.setDefaultClose0peration(JFrame.EXIT_ON CLOSE); 


JTextArea textArea = new JTextArea(); 
JScrollPane scrollPane = new JScrollPane(textArea); 
frame.add(scrollPane, BorderLayout.CENTER); 
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final JTextField dot = new JTextField(); 
dot.setEditable(false); 

JPanel dotPanel = new JPanel(new BorderLayout()); 
dotPanel.add(new JLabel("Dot: "), BorderLayout.WEST); 
dotPanel.add(dot, BorderLayout.CENTER); 
frame.add(dotPanel, BorderLayout.NORTH); 


final JTextField mark = new JTextField(); 
mark.setEditable(false); 

JPanel markPanel = new JPanel(new BorderLayout()); 
markPanel.add(new JLabel("Mark: "), BorderLayout.WEST); 
markPanel.add(mark, BorderLayout.CENTER); 
frame.add(markPanel, BorderLayout.SOUTH); 


CaretListener listener = new CaretListener() f 
public void caretUpdate(CaretEvent caretEvent) ( 
dot.setText(Integer.toString(caretEvent.getDot())); 
mark.setText(Integer.toString(caretEvent.getMark())); 
) 
E 


textArea.addCaretListener(listener); 


frame.setSize(250, 150); 
frame.setVisible(true); 
) 
5 
Event0Queue.invokeLater(runner); 
J 
) 


NavigationFilter Class 


Similar to the way you can limit input to the text component's document by associating 
a DocumentFilter with a Document, you can limit where the caret can go by associating a 
NavigationFilter with a JTextComponent. The class has three methods: 


public void setDot(NavigationFilter.FilterBypass fb, int dot, Position.Bias bias) 
public void moveDot(NavigationFilter.FilterBypass fb, int dot, Position.Bias bias) 


public int getNextVisualPositionFrom(JTextComponent text, int pos, 
Position.Bias bias, int direction, Position.Bias[] biasRet) 


To limit movement, you would typically override the first two, leaving the default imple- 
mentation of the latter. For instance, Listing 15-11 shows a program that has a reserved area 
(say, the title of a report) at the beginning of the JTextArea. If you try to set or move the caret 
(dot) to the reserved area, the filter rejects the change and moves the caret to after the area. 
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Listing 15-11. Restricting Caret Movement 


import javax.swing.*; 
import javax.swing.text.*; 
import javax.swing.event.*; 
import java.awt.*; 


public class NavigationSample ( 
private static final String START_STRING = "StartWn"; 
private static final int START_STRING_LENGTH = START_STRING.length(); 


public static void main(String args[]) ( 
Runnable runner = new Runnable() £ 
public void run() £ 
JFrame frame = new JFrame("Navigation Example"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


JTextArea textArea = new JTextArea(START_STRING); 
textArea.setCaretPosition(START_STRING_LENGTH); 
JScrollPane scrollPane = new JScrollPane(textArea); 
frame.add(scrollPane, BorderLayout.CENTER); 


NavigationFilter filter = new NavigationFilter() ( 
public void setDot(NavigationFilter.FilterBypass fb, int dot, 

Position.Bias bias) f 

if (dot < START_STRING_LENGTH) ( 
fb.setDot(START_STRING_LENGTH, bias); 

j else £ 
fb.setDot(dot, bias); 

J 


J 
public void moveDot(NavigationFilter.FilterBypass fb, int dot, 


Position.Bias bias) f 

if (dot < START_STRING_LENGTH) ( 
fb.setDot(START_STRING_LENGTH, bias); 

) else £ 
fb.setDot(dot, bias); 

) 

) 
y; 


textArea.setNavigationFilter(filter); 


frame.setSize(250, 150); 
frame.setVisible(true); 
E 
5 


EventQueue.invokeLater(runner); 
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Figure 15-12 shows the screen after typing some information into the text component. 


£ Navigation Example =10/xÍ 


Start 
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Figure 15-12. NavigationFilter sample 


Keymap Interface 


In “MVC-speak,” the keymap property of the text component is the Controller part. It maps 
KeyStroke objects to individual actions through the Keymap interface. (The KeyStroke class 
was discussed in Chapter 2.) When you register the KeyStroke to the JTextComponent with 
registerKeyboardAction(), as in the PopupSample program shown in Listing 15-9 earlier in 
this chapter, the text component stores this mapping from KeyStroke to Action in a Keymap. 
For instance, the Backspace key is mapped to delete the previous character. If you want to 
add another binding, you just register another keystroke. 


Note In reality, the Keymap is just a front to the ActionMap/InputMap pair. The JTextComponent 
relies on some internal workings to indirectly use the ActionMap/InputMap classes. 


You can also add actions for keystrokes directly to the Keymap. This allows you to share a 
key map across multiple text components, as long as they all share the same extended behavior. 


public interface Keymap ( 
// Properties 
public Action[ ] getBoundActions(); 
public KeyStroke[ ] getBoundKeyStrokes(); 
public Action getDefaultAction(); 
public void setDefaultAction(Action action); 
public String getName(); 
public Keymap getResolveParent(); 
public void setResolveParent(Keymap parent); 
// Other methods 
public void addActionForKeyStroke(KeyStroke keystroke, Action action); 
public Action getAction(KeyStroke keystroke); 
public KeyStroke[ ] getKeyStrokesForAction(Action action); 
public boolean isLocallyDefined(KeyStroke keystroke); 
public void removeBindings(); 
public void removeKeyStrokeBinding(KeyStroke keystroke); 
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For some applications, you may also want to remove keystrokes from the key map. For 
instance, the JTextField has an entry in the key map for the Enter key so that any registered 
ActionListener objects are notified. Ifthe JTextField is on a screen where a button has been 
designated as the default, pressing Enter won't select the default button, as desired. Getting rid 
of the default behavior is a simple process of requesting the removal of the single KeyStroke 
from the Keymap, as shown here: 


Keymap keymap = textField.getKeymap(); 
KeyStroke keystroke = KeyStroke.getKeyStroke(KeyEvent.VK_ENTER, O, false); 
keymap .removeKeyStrokeBinding(keystroke); 


Then, when you press Enter in the text field, the default button is activated, as shown in 
Figure 15-13. 


[2 Defecto AE 


(Testing 1-2-3 


 — 
Default Button Other Button 


Figure 15-13. Using the default button after removing the Enter binding from the Keymap 


The program source for the example in Figure 15-13 is shown in Listing 15-12. 


Listing 15-12. Working with the Default Button 


import javax.swing.*; 
import javax.swing.text.*; 
import java.awt.*; 

import java.awt.event.*; 


public class DefaultSample ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() £ 
public void run() £ 
JFrame frame = new JFrame("Default Example”); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


JTextField textField = new JTextField(); 
frame.add(textField, BorderLayout.NORTH); 


ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
System.out.println(actionEvent.getActionCommand() + " selected”); 
J 
E 
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JPanel panel = new JPanel(); 

JButton defaultButton = new JButton("Default Button"); 
defaultButton.addActionListener(actionListener); 

panel .add(defaultButton); 


JButton otherButton = new JButton("Other Button"); 
otherButton.addActionListener(actionListener); 
panel .add(otherButton); 


frame.add(panel, BorderLayout.SOUTH); 


Keymap keymap = textField.getKeymap(); 

KeyStroke keystroke = 
KeyStroke.getKeyStroke(KeyEvent.VK_ENTER, O, false); 

keymap.removeKeyStrokeBinding(keystroke); 


frame.getRootPane().setDefaultButton(defaultButton); 


frame.setSize(250, 150); 
frame.setVisible(true); 
Í 
5 
EventQueue.invokeLater(runner); 
) 
hi 


JTextComponent.KeyBinding Class 


The JTextComponent class stores the specific key bindings with the help of the 
JTextComponent .KeyBinding class. The current look and feel defines the default set 
of the key bindings for text components, such as the familiar Ctrl-X for cut, Ctrl-C for 
copy, and Ctrl-V for paste on a Microsoft Windows platform. 


Handling JTextField Events 


Dealing with events in Swing text components is completely different from dealing with events 
in AWT text components. Although you can still attach an ActionListener to listen forwhen the 
user presses the Enter key in the text field, attaching a KeyListener or a TextListener is no 
longer useful. 

To validate input, it is better to attach an InputVerifier than a FocusListener. However, 
input validation tends to be best left to the Document to accomplish or implemented when a 
user submits a form. 


Listening to JTextField Events with an ActionListener 


The JTextField will notify any registered ActionListener objects when the user presses Enter 
from within the text field. The component sends an ActionEvent to the ActionListener objects. 
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Part of this ActionEvent is an action command. By default, the action command of the event is 
the current contents ofthe component. With the Swing JTextField, you can also set this action 
command to be something different from the content. The JTextField has an actionCommand 
property. When itis set to null (the default setting), the action command for the ActionEvent 
takes the contents of the component. However, if you set the actionCommand property for the 
JTextField, then that actionCommand setting is part of the ActionEvent 

The following code demonstrates this difference. There are two text fields. When Enter is 
pressed in the first text field, causing the registered ActionListener to be notified, “Yo” is 
printed out. When Enter is pressed in the second text field, the contents are printed out. 


JTextField nameTextField = new JTextField(); 
JTextField cityTextField = new JTextField(); 
ActionListener actionListener = new ActionListener() f 
public void actionPerformed(ActionEvent actionEvent) ( 
System.out.println("Command: " + actionEvent.getActionCommand()); 
) 
A 
nameTextField.setActionCommand("Yo"”); 
nameTextField.addActionListener(actionListener); 
cityTextField.addActionListener(actionListener); 


Listening to JTextField Events with an KeyListener 


With the Swing text components, you normally don't listen for key events with a KeyListener— 
at least not to validate input. Running the following example demonstrates that you can still 
find out when a key has been pressed or released, not just when it has been typed. 


KeyListener keyListener = new KeyListener() ( 
public void keyPressed(KeyEvent keyEvent) ( 
printIt("Pressed", keyEvent); 
) 
public void keyReleased(KeyEvent keyEvent) ( 
printIt("Released", keyEvent); 
) 
public void keyTyped(KeyEvent keyEvent) ( 
printIt("Typed", keyEvent); 
) 
private void printIt(String title, KeyEvent keyEvent) ( 
int keyCode = keyEvent.getKeyCode(); 
String keyText = KeyEvent.getKeyText(keyCode); 
System.out.println(title + " : " + keyText); 
) 
$; 
nameTextField.addKeyListener(keyListener); 
cityTextField.addKeyListener(keyListener); 
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Listening to JTextField Events with an InputVerifier 


Implementing the InputVerifier interface allows you to do field-level validation ofa JTextField. 
Before focus moves out of a text component, the verifier runs. Ifthe input isn't valid, the verifier 
rejects the change and keeps input focus within the given component. 

In the following example, if you try to move the input focus beyond the text field, you'!l 
find that you can't, unless the contents of the text field are empty or the contents consist ofthe 
string "Exit". 


InputVerifier verifier = new InputVerifier() f 
public boolean verify(JComponent input) f 
final JTextComponent source = (JTextComponent) input; 
String text = source.getText(); 
if ((text.length() != 0) 38 !(text.equals("Exit"))) ( 
Runnable runnable = new Runnable() £ 
public void run() £ 
JOptionPane.shonMessageDialog (source, "Can't leave.", 
"Error Dialog", JOptionPane.ERROR_MESSAGE); 
J 
A 
EventQueue.invokelLater(runnable); 
return false; 
) else [ 
return true; 
J 
hi 
A 
nameTextField.setInputVerifier(verifier); 
cityTextField.setInputVerifier(verifier); 


Listening to JTextField Events with a DocumentListener 


To find out when the contents of the text component changed, you need to associate a listener 
with the data model. In this case, the data model is Document and the listeneris a DocumentListener. 
The following example just tells you when and how the model changed. Remember that 
changedUpdate() is for attribute changes. Do not use a DocumentListener for input validation. 


DocumentListener documentListener = new DocumentListener() ( 
public void changedUpdate(DocumentEvent documentEvent) £ 
printIt(documentEvent); 


public void insertUpdate(DocumentEvent documentEvent) ( 
printIt(documentEvent); 


public void removeUpdate(DocumentEvent documentEvent) ( 
printIt(documentEvent); 


private void printIt(DocumentEvent documentEvent) ( 
DocumentEvent.EventType type = documentEvent.getType(); 
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String typeString = null; 
if (type.equals(DocumentEvent.EventType.CHANGE)) ( 
typeString = "Change"; 
j else if (type.equals(DocumentEvent.EventType.INSERT)) ( 
typeString = "Insert"; 
j else if (type.equals(DocumentEvent.EventType.REMOVE)) € 
typeString = "Remove"; 
) 
System.out.print("Type + typeString + " / "); 
Document source = documentEvent.getDocument (>; 
int length = source.getLength(); 
try ( 
System.out.println("Contents: " + source.getText(0, length)); 
Y catch (BadLocationException badLocationException) f 
System.out.println("Contents: Unknown"); 
) 
h 
h; 
nameTextField.getDocument () .addDocumentListener(documentListener); 
cityTextField.getDocument (). addDocumentListener(documentListener); 


" 


" 


Putting It All Together 


Now that you've seen the usage of the listeners separately, let's put them all together within 
one example. Figure 15-14 shows the end result of this endeavor. Keep in mind that the magic 
word to tab out of a component is “Exit.” 


Jalx] 


Name: (Exit Ñ | 


city: [D'oh] 


Figure 15-14. JTextField event demonstration 
The source behind the program in Figure 15-14 is shown in Listing 15-13. 


Listing 15-13. Text Event Handling 


import javax.swing.*; 
import javax.swing.text.*; 
import javax.swing.event.*; 
import java.awt.*; 

import java.awt.event.*; 


public class JTextFieldSample ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() £ 
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public void run() ( 
JFrame frame = new JFrame("TextField Listener Example"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


Panel namePanel = new JPanel(new BorderLayout()); 
Label nameLabel = new JLabel("Name: "); 
nameLabel.setDisplayedMnemonic(KeyEvent .VK_N); 
JTextField nameTextField = new JTextField(); 
nameLabel.setLabelFor(nameTextField); 
namePanel.add(nameLabel, BorderLayout.WEST); 
namePanel.add(nameTextField, BorderLayout.CENTER); 
frame.add(namePanel, BorderLayout.NORTH); 


JPanel cityPanel = new JPanel(new BorderLayout()); 
Jlabel citylLabel = new JLabel("City: "); 
cityLabel.setDisplayedMnemonic(KeyEvent.VK_C); 
JTextField cityTextField = new JTextField(); 
citylabel.setlabelFor(cityTextField); 
cityPanel.add(cityLabel, BorderLayout.WEST); 
cityPanel.add(cityTextField, BorderlLayout.CENTER); 
frame.add(cityPanel, BorderLayout.SOUTH); 


ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
System.out.println("Command: " + actionEvent.getActionCommand()); 
) 
E 
nameTextField.setActionCommand("Yo"); 
nameTextField.addActionListener(actionListener); 
cityTextField.addActionListener(actionListener); 


KeyListener keyListener = new KeyListener() 
public void keyPressed(KeyEvent keyEvent) 
printIt("Pressed", keyEvent); 


1 
1 
public void keyReleased(KeyEvent keyEvent) ( 


printIt("Released", keyEvent); 


public void keyTyped(KeyEvent keyEvent) ( 
printIt("Typed", keyEvent); 


h 
private void printIt(String title, KeyEvent keyEvent) ( 
int keyCode = keyEvent.getKeyCode(); 
String keyText = KeyEvent.getKeyText(keyCode); 
System.out.println(title + " : " + keyText +" / "+ 
keyEvent .getKeyChar()); 


A 


CHAPTER 15 BASIC TEXT COMPONENTS 


nameTextField.addKeyListener(keyListener); 
cityTextField.addKeyListener(keyListener); 


InputVerifier verifier = new InputVerifier() f 
public boolean verify(JComponent input) ( 
final JTextComponent source = (JTextComponent) input; 
String text = source.getText(); 
if ((text.length() != 0) 32 !(text.equals("Exit"))) ( 
JOptionPane.shonMessageDialog (source, "Can't leave.", 
"Error Dialog", JOptionPane.ERROR_MESSAGE); 
return false; 
) else £ 
return true; 
y 
J 
A 
nameTextField.setInputVerifier(verifier); 
cityTextField.setInputVerifier(verifier); 


DocumentListener documentListener = new DocumentListener() ( 
public void changedUpdate(DocumentEvent documentEvent) £ 
printIt(documentEvent); 

) 
public void insertUpdate(DocumentEvent documentEvent) f 
printIt(documentEvent); 

) 
public void removeUpdate(DocumentEvent documentEvent) f 
printIt(documentEvent); 


y 

private void printIt(DocumentEvent documentEvent) ( 

DocumentEvent.EventType type = documentEvent.getType(); 

String typeString = null; 

if (type.equals(DocumentEvent.EventType.CHANGE)) 4 
typeString = "Change"; 

j else if (type.equals(DocumentEvent.EventType.INSERT)) ( 
typeString = "Insert"; 

j else if (type.equals(DocumentEvent.EventType.REMOVE)) ( 
typeString = "Remove"; 

J 

System.out.print("Type + typeString + " / "); 

Document source = documentEvent.getDocument (>); 

int length = source.getLength(); 


" 
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try ( 
System.out.println("Contents: " + source.getText(0, length)); 
) catch (BadLocationException badLocationException) ( 
System.out.println("Contents: Unknown"); 
) 
) 
E 
nameTextField.getDocument().addDocumentListener(documentListener); 
cityTextField.getDocument () . addDocumentListener(documentListener); 


" 


frame.setSize(250, 100); 
frame.setVisible(true); 
Í 
E 
EventQueue.invokeLater(runner); 
y 
) 


Customizing a JTextField Look and Feel 


Each installable Swing look and feel provides a different JTextField appearance and set of 
default UIResource values. The available set of 25 UIResource-related properties for a JTextField is 
shown in Table 15-5. 


Table 15-5. JTextField UlResource Elements 


Property String Object Type 
text Color 
textHighlight Color 
textHighlightText Color 
textInactiveText Color 
TextField.actionMap ActionMap 
TextField.background Color 
TextField.border Border 
TextField.caretAspectRatio Number 
TextField.caretBlinkRate Integer 
TextField.caretForeground Color 
TextField.darkShadow Color 
TextField.disabledBackground Color 
TextField.focusInputMap InputMap 


TextField.+font Font 


CHAPTER 15 BASIC TEXT COMPONENTS 


Table 15-5. JTextField UlResource Elements (Continued) 


Property String Object Type 
TextField.foreground Color 
TextField.highlight Color 
TextField.inactiveBackground Color 
TextField.inactiveForeground Color 
TextField.keyBindings KeyBinding[ ] 
TextField. light Color 
TextField.margin Insets 
TextField.selectionBackground Color 
TextField.selectionForeground Color 
TextField.shadow Color 
TextFieldUlI String 


Figure 15-15 shows the appearance of the JTextField component for the preinstalled set 
of look and feel types: Motif, Windows, and Ocean. 


-10/x) ATTE 


Name: Exit Name: (82 


City: | City: 
Motif Windows 
-l0/xi 
Name: Exit 


Ocean 


Figure 15-15. JTextField under different look and feel types 


JPasswordField Glass 


The JPasswordField component is designed for input of passwords. Instead of echoing what 
the user types, a special input mask is displayed. It works like a JTextField with an input mask 
of *. You can't unset the mask, nor can you cut or copy the contents ofthe password component. 
The intention is to enhance security. 


Creating a JPasswordField 


The JPasswordField class has the same five constructors as the JTextField: 
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public JPasswordField() 
JPasswordField passwordField = new JPasswordField(); 


public JPasswordField(String text) 
JPasswordField passwordField = new JPasswordField("Initial Password"); 


public JPasswordField(int columnWidth) 
JPasswordField passwordField = new JPasswordField(14); 


public JPasswordField(String text, int columnWidth) 
JPasswordField passwordField = new JPasswordField("Initial Password", 14); 


public JPasswordField(Document model, String text, int columnWidth) 
JPasswordField passwordField = new JPasswordField(aModel, "Initial Password", 14); 


With the no-argument constructor, you get an empty input field zero columns wide, a 
default initial Document model, and an echo character of *. Although you can specify the initial 
text in the constructor, you're usually prompting a user for a password to verify the user's iden- 
tity, not to see if the user can submit a form. Therefore, a JPasswordField tends to be empty at 
startup. As with the JTextField, you can also specify the initial width, assuming that the layout 
manager of the container in which the JPasswordField is placed will honor this request. 

You can also specify the Document data model for the password field in a constructor. When 
specifying the Document data model, you should specify a null initial-text argument; otherwise, 
the current contents ofthe document will be replaced by the initial text for the password field. 
In addition, you should not try to use a custom Document with a JPasswordField. Because the 
component doesn't display any visual feedback besides how many characters have been 
entered, it can be confusing to a user if you tried to restrict input to only numeric data. 


JPasswordField Properties 
Table 15-6 shows the four properties of JPasswordField. 


Table 15-6. JPasswordField Properties 


Property Name Data Type Access 

accessibleContext AccessibleContext Read-only 
echoChar char Read-write 
password char[ ] Read-only 
UlClassID String Read-only 


Setting the echoChar property allows you to use a mask character other than the default 
asterisk (*) character. Ifthe echoChar property is set to the character* 10000 (0), the public 
boolean echoCharIsSet() method returns false. In all other cases, the method returns true. 
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Caution The JPasswordField also has a deprecated read-only text property, which you should avoid 
using. You should use the password property instead, because it returns a char [ ] that can be cleared 
immediately after usage. A String must wait for the garbage collector to dispose of it. 


Customizing a JPasswordField Look and Feel 


The JPasswordField is a subclass of a JTextField. It has the same appearance under all the 
predefined look and feel types as the JTextField (see Figure 15-15). The one difference is that 
the current echoChar property setting masks the content. This is shown in Figure 15-16. The top 
text component is a JTextField; the bottom one is a JPasswordField. 


[> rerswordtiamale ASE 


Username: [president 


Password: aaa 


Figure 15-16. JPasswordField sample in Ocean theme 


The set of 17 UTResource-related properties for a JPasswordField is shown in Table 15-7. 


Table 15-7. JPasswordField UlResource Elements 


Property String 
PasswordField.actionMap 
PasswordField.background 
PasswordField.border 
PasswordField.caretAspectRatio 
PasswordField.caretBlinkRate 
PasswordField.caretForeground 
PasswordField.disabledBackground 
PasswordField.focusInputMap 
PasswordField. font 
PasswordField.foreground 
PasswordField.inactiveBackground 


PasswordField.inactiveForeground 


PasswordField.keyBindings 


Object Type 
ActionMap 
Color 
Border 
Number 
Integer 
Color 
Color 
InputMap 
Font 
Color 
Color 
Color 


KeyBinding[ ] 
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Table 15-7. JPasswordField UlResource Elements (Continued) 


Property String Object Type 
PasswordField.margin Insets 
PasswordField.selectionBackground Color 
PasswordField.selectionForeground Color 
PasswordFieldUlI String 


JFormattedTextField Class 


The JFormattedTextField provides support for the input of formatted text. When the compo- 
nent is created, you define a mask for the input. That mask can be in the form of one of four 
styles: a java.text.Format object, an AbstractFormatter, an AbstractFormatterFactory, oran 
actual value of a different type (such as 3.141592). 

The system provides several abstract formatters for you to work with, depending on the 
type of data you want a user to input. For instance, the NumberFormatter is available to enter 
numbers, and the DateFormatter is available for entering dates. There is also a MaskFormatter for 
describing input with edit strings, like "XXX-XX-XXX" for a United States social security number. If 
you want different display and edit formats, you can use the AbstractFormatterFactory. You'”!l 
learn more about formatters and formatter factories in Chapter 16. 


Creating a JFormattedTextField 


There are six constructors for the JFormattedTextField class: 


public JFormattedTextField() 
JFormattedTextField formattedField = new JFormattedTextField(); 


public JFormattedTextField(Format format) 
DateFormat format = new SimpleDateFormat ("yyyy--MMMM--dd"); 
JFormattedTextField formattedField = new JFormattedTextField(format); 


public JFormattedTextField(JFormattedTextField.AbstractFormatter formatter) 
DateFormat displayFormat = new SimpleDateFormat("yyyy--MMMM--dd"); 
DateFormatter displayFormatter = new DateFormatter(displayFormat); 
JFormattedTextField formattedField = new JFormattedTextField(displayFormatter); 


public JFormattedTextField(JFormattedTextField.AbstractFormatterFactory factory) 
DateFormat displayFormat = new SimpleDateFormat("yyyy--MMMM- -dd">); 
DateFormatter displayFormatter = new DateFormatter(displayFormat); 
DateFormat editFormat = new SimpleDateFormat("MM/dd/yy"); 
DateFormatter editFormatter = new DateFormatter(editFormat); 
DefaultFormatterFactory factory = new DefaultFormatterFactory( 
displayFormatter, displayFormatter, editFormatter); 
JFormattedTextField formattedField = new JFormattedTextField(factory); 
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public JFormattedTextField(JFormattedTextField.AbstractFormatterFactory factory, 
Object currentValue) 

DateFormat displayFormat = new SimpleDateFormat ("yyyy--MMMM--dd"); 

DateFormatter displayFormatter = new DateFormatter(displayFormat); 

DateFormat editFormat = new SimpleDateFormat ("MM/dd/yy"); 

DateFormatter editFormatter = new DateFormatter(editFormat); 

DefaultFormatterFactory factory = new DefaultFormatterFactory( 
displayFormatter, displayFormatter, editFormatter); 

JFormattedTextField formattedField = new JFormattedTextField(factory, new Date()); 


public JFormattedTextField(Object value) 
JFormattedTextField formattedField = new JFormattedTextField(new Date()); 


The no-argument version requires you to configure it later. The other constructors allow 
you to configure what and how input will be accepted into the component. 


JFormattedTextField Properties 


Table 15-8 shows the eight properties of JFormattedTextField. Instead of getting the contents 
ofthe JFormattedTextField as a String via the text property, as you would with a JTextField, 
you get it as an Object via the value property. Thus, if your formatter were for a Date object, the 
value you get back could be cast to type java.util.Date. 


Table 15-8. JFormattedTextField Properties 


Property Name Data Type Access 

actions Action[ ] Read-only 
document Document Write-only 
editValid boolean Read-only 
focusLostBehavior int Read-write 
formatter JFormattedTextField.AbstractFormatter Read-only 
formatterFactory JFormattedTextField.AbstractFormatterFactory Read-write bound 
UlClassID String Read-only 

value Object Read-write bound 


Listing 15-14 demonstrates the user of JFormattedTextField with custom formatters and 
factories. Notice that when you edit the bottom text field, the display format and edit format 
are different. 
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Listing 15-14. JFormattedTextField Example 


im 
im 
im 
im 
im 


port 
port 
port 
port 
port 
port 
port 


blic 


javax.swing.*; 
javax.swing.text.*; 
javax.swing.event.*; 
java.awt.*; 
java.awt.event.*; 
java.util.*; 
java.text.*; 


class FormattedSample ( 


public static void main(final String args[]) ( 


Runnable runner = new Runnable() f 


public void run() ( 


JFrame frame = new JFrame("Formatted Example"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


Panel datePanel = new JPanel(new BorderLayout()); 

Label datelabel = new JLabel("Date: "); 
dateLabel.setDisplayedMnemonic(KeyEvent.VK_D); 

DateFormat format = new SimpleDateFormat ("yyyy--MMMM--dd"); 
JFormattedTextField dateTextField = new JFormattedTextField(format); 
datelLabel.setLabelFor(dateTextField); 

datePanel.add(dateLabel, BorderLayout.WEST); 
datePanel.add(dateTextField, BorderLayout.CENTER); 
frame.add(datePanel, BorderLayout.NORTH); 


JPanel date2Panel = new JPanel(new BorderLayout()); 

JLabel date2Label = new JLabel("Date 2: "); 

date2Label.setDisplayedMnemonic(KeyEvent.VK_A); 

DateFormat displayFormat = new SimpleDateFormat ("yyyy--MMMM--dd"); 

DateFormatter displayFormatter = new DateFormatter(displayFormat); 

DateFormat editFormat = new SimpleDateFormat("MM/dd/yy"); 

DateFormatter editFormatter = new DateFormatter(editFormat); 

DefaultFormatterFactory factory = new DefaultFormatterFactory( 
displayFormatter, displayFormatter, editFormatter); 

JFormattedTextField date2TextField = new JFormattedTextField(factory, 
new Date()); 

date2Label.setlabelFor(date2TextField); 

date2Panel.add(date2Label, BorderLayout.WEST); 

date2Panel.add(date2TextField, BorderLayout.CENTER); 

frame.add(date2Panel, BorderLayout.SOUTH); 


ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
JFormattedTextField source = 
(JFormattedTextField)actionEvent.getSource(); 
Object value = source.getValue(); 
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" 


System.out.println("Class: 
System.out.println("Value: 


+ value.getClass()); 
+ value); 


" 


) 
$; 


dateTextField.addActionListener(actionListener); 
date2TextField.addActionListener(actionListener); 


frame.setSize(250, 100); 
frame.setVisible(true); 


) 
le 


EventQueue.invokeLater(runner); 


J 
, 


Customizing a JFormattedTextField Look and Feel 


Like the JPasswordField, JFormattedTextField is a subclass of a JTextField. It, too, has the 
same appearance as the JTextField under all the predefined look and feel types (see Figure 15-15). 
To customize its display, you can change any of the set of 16 UlIResource-related properties for 


a JFormattedTextField, as shown in Table 15-9. 


Table 15-9. JFormattedTextField UlResource Elements 


Property String Object Type 
FormattedTextField.actionMap ActionMap 
FormattedTextField.background Color 
FormattedTextField.border Border 
FormattedTextField.caretAspectRatio Number 
FormattedTextField.caretBlinkRate Integer 
FormattedTextField.caretForeground Color 
FormattedTextField.focusInputMap InputMap 
FormattedTextField. font Font 
FormattedTextField.foreground Color 
FormattedTextField.inactiveBackground Color 
FormattedTextField.inactiveForeground Color 
FormattedTextField.keyBindings KeyBinding[ ] 
FormattedTextField.margin Insets 
FormattedTextField.selectionBackground Color 
FormattedTextField.selectionForeground Color 
FormattedTextFieldUI String 
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JTextArea Class 


The JTextArea component is the text component for multiple-line input. Similar to the 
JTextField, the data model for a JTextArea is the PlainDocument implementation of the 
Document interface. Therefore, the JTextArea is limited to single-attributed text. As with other 
Swing components that may require scrolling, the JTextArea doesn't support scrolling itself. 
You need to place each JTextArea within a JScrol1Pane to allow a user to properly scroll through 
the contents of a JTextArea. 


Creating a JTextArea 


There are six constructors for creating a JTextArea: 


public JTextArea() 
JTextArea textArea = new JTextArea(); 


public JTextArea(Document document) 
Document document = new PlainDocument(); 
JTextArea textArea = new JTextArea(document); 


public JTextArea(String text) 
JTextArea textArea = new JTextArea("..."); 


public JTextArea(int rows, int columns) 
JTextArea textArea = new JTextArea(10, 40); 


public JTextArea(String text, int rows, int columns) 
JTextArea textArea = new JTextArea("...", 10, 40); 


public JTextArea(Document document, String text, int rows, int columns) 
JTextArea textArea = new JTextArea(document, null, 10, 40); 


Unless otherwise specified, the text area is able to hold zero rows and columns of content. 
Although this might sound like a serious limitation, you're just telling the text area to let the 
current LayoutManager worry about the size of your text area. The contents ofthe JTextArea are 
initially empty unless specified from either the starting text string or the Document model. 


Note Other initial settings for a JTextArea include having a tab stop every eight positions and turning off 
word wrap. For more on tab stops, see the TabStop and TabSet class descriptions in Chapter 16. 


After creating a JTextArea, remember to place the JTextArea into a JScrol1Pane. Then if 
there isn't sufficient space on the screen, the JScrollPane will manage the scrolling for you. 


CHAPTER 15 BASIC TEXT COMPONENTS 


JTextArea textArea = new JTextArea(); 
JScrollPane scrollPane = new JScrollPane(textArea); 
content.add(scrollPane); 


Figure 15-17 shows how a JTextArea looks within a JScrol1Pane and outside a JScrol1Pane. In 
the JTextArea not in the JscrollPane, you can't see the text that falls below the bottom screen 
border. By design, moving the cursor into that area doesn't cause the content at the top to 
move up. 


[+ reanreatome AE 


import javax.swing.*; 19 [a] 
import java.awt*; 


public class [E vessamot í 
public static void mall mainífinal String 
Runnablk runner= her= new Runnable—| 
public void runQ ( has ps 
Strinatitlo= farns Jal 4 ll | » 


Figure 15-17. A JTextArea without a JScrollPane and one within a JScrollPane 


JTextArea Properties 
Table 15-10 shows the 12 properties of JTextArea. 


Table 15-10. JTextArea Properties 


Property Name Data Type Access 
accessibleContext  AccessibleContext  Read-omly 
columns int Read-write 

font Font Write-only 
lineCount int Read-only 
lineWrap boolean Read-write bound 
preferredScrollableViewportSize Dimension Read-only 
preferredSize Dimension Read-only 

rows int Read-write 
scrollableTracksViemportWidth boolean Read-only 
tabSize int Read-write bound 
UlClassID String Read-only 


wrapStyleWdord boolean Read-write bound 
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The rows and columns properties come directly from the constructor arguments. The 
preferredScrollableViewportSize and scrollableTracksViewportWidth properties come from 
implementing the Scrollable interface for scrolling support. The font and preferredSize 
properties merely customize the behavior inherited from JTextComponent. 

That leaves the more interesting properties of lineCount, tabSize, and lineWrap with 
wrapStyleWord to examine. The lineCount property allows you to find out how many lines are 
in the text area. This is useful for sizing purposes. The tabSize property allows you to control 
the tab position interval within the text area. By default, this value is 8. 

The linewWrap and wrapStyleWdord properties work together. By default, the wrapping of 
longlinesis disabled. Ifyou enable line wrapping (by setting the lineWrap property to true), the 
point at which long lines wrap depends on the wrapStyleWord property setting. Initially, this 
property is false, which means that ifthe lineWrap property is true, line wrapping happens at 
character boundaries. Ifboth lineWrap and wrapStyleWord are true, then each word from a line 
that doesn't fitis wrapped to another line, as itis in a word processor. So, to get the word wrap 
capabilities that most people want, you should set both properties to true for your JTextArea: 


JTextArea textArea = new JTextArea("..."); 
textArea.setlLineWrap(true); 
textArea.setWrapStyleWord(true); 

JScrollPane scrollPane = new JScrollPane(textArea); 


Note The Ctrl-Tab and Shift-Ctrl-Tab key combinations allow users to change focus from within 
JTextArea components without needing to subclass the component. 


Handling JTextArea Events 


No events are specific to a JTextArea. You can use one of the inherited listeners from 
JTextComponent (or one of its parents) or attach an InputVerifier. 

At times, you'll just have a JTextArea on the screen and get its contents after the user 
presses a button. Other times, there's a bit more planning involved, where you might monitor 
input as it is entered, and possibly convert something like : -) to a smiley face: O. 


Customizing a JTextArea Look and Feel 


Each installable Swing look and feel provides a different JTextArea appearance and set of 
default UTResource values. Figure 15-18 shows the appearance ofthe JTextArea component for 
the preinstalled set of look and feel types. Notice that the primary difference in the appearance 
of each is the scrollbar from the JScrol1Pane, which is not a part of the actual JTextArea. 
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Figure 15-18. JTextArea under different look and feel types 


The available set of 15 UIResource-related properties for a JTextArea is listed in Table 15-11. 


Table 15-11. JTextArea UlResource Elements 


Property String Object Type 
TextArea.actionMap ActionMap 
TextArea.background Color 
TextArea.border Border 
TextArea.caretAspectRatio Number 
TextArea.caretBlinkRate Integer 
TextArea.caretForeground Color 
TextArea.focusInputMap InputMap 
TextArea.font Font 
TextArea.foreground Color 
TextArea.inactiveForeground Color 
TextArea.keyBindings KeyBinding[ ] 
TextArea.margin Insets 
TextArea.selectionBackground Color 
TextArea.selectionForeground Color 
TextAreaUl String 
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JEditorPane Class 


The JEditorPane class provides the ability to display and edit multiple-attributed text. While 
the JTextField and JTextArea support only single-color, single-font content, the JEditorPane 
allows you to tag your content with various styles (such as bold, italics, 14-point Helvetica, 
right-justified paragraphs) or with the appearance ofan HTML viewer, as shown in Figure 15-19. 


£ EditorPane Example =10/x/ 


About O 09 le: | || Search our site 
Maq ia go 
a 


a 


Check our Google Blog. Help and How to Search Advertising 

Basics, Advanced Features, £dWords, AdSense... 
AÑ FAOS... = 
New! The Google Mini Business Solutions 
— 4. Google Web Search Google Search Appliance, Google Mini, 
Features WebSearch... 
Buy Google in a box online. Translation, I'm Feeling Lucky, 

Cached... Webmaster Info 


Guidelines, Ranking questions... 


O ta Google Services € Tools e ñ 
TV piogeaits tit Toolbar, Google Web APls, Submitting your Site || 
E Buttons... How Google adds URLs... 
Google Video. 
Google Labs 
Keyhole Ideas, Demos, Experiments... 


* ea 
Take a virtual world tour. Our Company More Google 


Download Keyhole. 


4] 


Figure 15-19. Sample JEditorPane as an HTML viewer 


Note The HTML support for JEditorPane is only at the HTML 3.2 level with some extensions, whereas 
HTML 4.0x is the current version as of this writing. Cascading Style Sheets (CSS) are partially supported. 


The JEditorPane supports the display and editing of multiple-attributed text through the 
help of an EditorKit specific to the text-markup mechanism. Predefined kits exist to support 
raw text, HTML documents, and Rich Text Format (RTF) documents. Because the content is 
multiple-attributed, the PlainDocument model is no longer sufficient. Instead, Swing provides a 
StyledDocument in the form of the DefaultStyledDocument class for maintaining the document 
model. The remaining part of the mix is the new HyperlinkListener/HyperlinkEvent event- 
handling pair for monitoring hyperlink operations within the document. 
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Creating a JEditorPane 


The JEditorPane has four constructors: 


public JEditorPane() 
JEditorPane editorPane = new JEditorPane(); 


public JEditorPane(String type, String text) 

String content = "<H1>Got Java?</H1>"; 

String type = "text/html"; 

JEditorPane editorPane = new JEditorPane(type, content); 


public JEditorPane(String urlString) throws IOException 
JEditorPane editorPane = new JEditorPane("http://www.apress.com"); 


public JEditorPane(URL url) throws IOException 
URL url = new URL("http://www.apress.com"); 
JEditorPane editorPane = new JEditorPane(url); 


The no-argument constructor creates an empty JEditorPane. If you want to initialize the 
contents, you can directly specify the text and its MIME type. Or, you can specify the URL for 
where to get the contents. The URL can be specified as either a String or a URL object. When 
you specify the contents as a URL, the JEditorPane determines the MIME type from the response. 


JEditorPane Properties 


Table 15-12 shows the 11 properties of JEditorPane. Most of the properties just customize the 
behavior of the parent classes. 


Table 15-12. JEditorPane Properties 


Property Name Data Type Access 
accessibleContext AccessibleContext Read-only 
contentType String Read-write 
editorKit EditorKit Read-write bound 
hyperlinkListeners HyperlinkListener[ ] Read-only 

page URL Read-write bound 
page String Write-only bound 
preferredSize Dimension Read-only 
scrollableTracksViemportHeight boolean Read-only 
scrollableTracksViemportWidth boolean Read-only 

text String Read-write 


UlClassID String Read-only 


575 


576 


CHAPTER 15 BASIC TEXT COMPONENTS 


Note The page property is nonstandard in the sense it has two setter methods, but only one getter. 


Four interesting properties of JEditorPane are the editorKit, contentType, page, and text. 
The editorKit property is configured based on the type of content in the editor pane. Itis 
covered in more detail in Chapter 16, with its DefaultEditorKit, StyledEditorKit, and 
HTMLEditorKit implementations. The contentType property represents the MIME type of the 
content inside the document. This property tends to be automatically set when you set up 
the content in the constructor (or elsewhere). In the event the editor kitis unable to determine the 
MIME type, you can manually set it. The three MIME types with built-in support are text/html, 
text/plain, and text/rtf, as reported by the getContentType() method of the predefined 
editor kits. 

The page property allows you to change the displayed contents to reflect the contents ofa 
specific URL so that you can use the contents in some manner not programmed into the envi- 
ronment. The text property allows you to find out what the textual content is based on the 
current Document model. 


Handling JEditorPane Events 


Because JEditorPane is just another text area component with some special display character- 
istics, it supports the same set of listeners for event handling as does the JTextArea component. 
In addition, the JEditorPane provides a special listener-event combination to deal with hyper- 
links within a document. 

The HyperlinkListener interface defines one method, public void hyperlinkUpdate 
(HyperlinkEvent hyperlinkEvent), which works with a HyperlinkEvent to respond to—not 
surprisingly—a hyperlink event. The event includes a HyperlinkEvent.EventType that reports 
on the type of event and allows you to react differently, either by following the link when 
selected or possibly changing the cursor when moving the mouse over (or off) the hyperlink 
(although this happens by default). 

Here is the HyperlinkListener definition: 


public interface HyperlinkListener implements EventListener ( 
public void hyperlinkUpdate(HyperlinkEvent hyperlinkEvent); 
J 


And, here is the HyperlinkEvent definition: 


public class HyperlinkEvent extends EventObject ( 

// Constructors 
public HyperlinkEvent(Object source, HyperlinkEvent.EventType type, URL url); 
public HyperlinkEvent(Object source, HyperlinkEvent.EventType type, URL url, 
String description); 
public HyperlinkEvent(Object source, HyperlinkEvent.EventType type, URL url, 
String description, Element sourceElement) 
// Properties 
public String getDescription(); 
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public HyperlinkEvent.EventType getEventType(); 
public Element getSourceElement(); 
public URL getURL(); 

ñ 


The hyperlink event types will be one of three constants within the HyperlinkEvent .EventType 
class: 


+ ACTIVATED: Usually involving a mouse click over the appropriate content 
+ ENTERED: Moving the mouse over the hyperlink content 
e EXITED: Moving the mouse out of the hyperlink content 


Therefore, if you want to create a HyperlinkListener that displays the URL in a status bar 
while over a hyperlink and follows the hyperlink when activated, you can create your own 
miniature HTML help viewer. The HyperlinkListener implementation in Listing 15-15 will do 
the trick for you. There are println statements present in the listener to display the URLwhen 
the mouse is over the URL and when the URLis activated. 


Listing 15-15. HyperlinkListener Example 


import java.awt.*; 

import javax.swing.*; 
import javax.swing.text.*; 
import javax.swing.event.*; 
import java.io.*; 

import java.net.*; 


public class ActivatedHyperlinkListener implements HyperlinkListener ( 


Frame frame; 
JEditorPane editorPane; 


public ActivatedHyperlinkListener(Frame frame, JEditorPane editorPane) ( 
this.frame = frame; 
this.editorPane = editorPane; 


J 


public void hyperlinkUpdate(HyperlinkEvent hyperlinkEvent) £ 
HyperlinkEvent.EventType type = hyperlinkEvent.getEventType(); 
final URL url = hyperlinkEvent.getURL(); 
if (type == HyperlinkEvent.EventType.ENTERED) € 
System.out.println("URL: "+ url ); 
y else if (type == HyperlinkEvent.EventType.ACTIVATED) ( 
System.out.println("Activated"); 
Runnable runner = new Runnable() f 
public void run() ( 
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// Retain reference to original 
Document doc = editorPane.getDocument(); 
try ( 
editorPane.setPage(url); 
$ catch (IOException ioException) f 
JOptionPane.showMessageDialog(frame, "Error following link", 
"Invalid link", JOptionPane.ERROR_MESSAGE); 
editorPane.setDocument (doc); 
Í 
) 
5 
EventQueue.invokelLater(runner); 
) 
J 
y 


Tip Don't forget to make the JEditorPane read-only with a call to setEditable(false). Otherwise, 
the viewer acts as an editor. 


Listing 15-16 is a complete example using our new ActivatedHyperlinkListener class. The 
frame it creates looks like the page shown earlier in Figure 15-19, although in the figure, the 
About link has been followed. 


Listing 15-16. JEditorPane Example 


import javax.swing.*; 
import javax.swing.event.*; 
import java.awt.*; 

import java.io.*; 


public class EditorPaneSample ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("EditorPane Example"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


ol 
JEditorPane editorPane = new JEditorPane("http://www.google.com"); 
editorPane.setEditable(false); 


HyperlinkListener hyperlinkListener = 
new ActivatedHyperlinkListener(frame, editorPane); 
editorPane.addHyperlinkListener(hyperlinkListener); 


CHAPTER 15 BASIC TEXT COMPONENTS 


JScrollPane scrollPane = new JScrollPane(editorPane); 
frame.add(scrollPane); 

$ catch (IOException e) ( 
System.err.println("Unable to load: 


J 


" 


+ €); 


frame.setSize(640, 480); 
frame.setVisible(true); 


) 
E; 


EventQueue.invokeLater(runner); 


y 
E 


Customizing a JEditorPane Look and Feel 


The appearance ofthe JEditorPane is similar to that ofa JTextArea (see Figure 15-18). Although 
the supported contents differ, the look-and-feel-related attributes usually aren't different. 

The available setof 15 UIResource-related properties for a JEditorPane is shown in Table 15-13. 
Their names are similar to those ofthe JTextArea settings. 


Table 15-13. JEditorPane UlResource Elements 


Property String Object Type 
EditorPane.actionMap ActionMap 
EditorPane.background Color 
EditorPane.border Border 
EditorPane.caretAspectRatio Number 
EditorPane.caretBlinkRate Integer 
EditorPane.caretForeground Color 
EditorPane.focusInputMap InputMap 
EditorPane.font Font 
EditorPane.foreground Color 
EditorPane.inactiveForeground Color 


EditorPane.keyBindings 


KeyBinding[ ] 


EditorPane.margin Insets 
EditorPane.selectionBackground Color 
EditorPane.selectionForeground Color 


EditorPaneUl 


String 
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JTextPane Class 


The JTextPane is a specialized form of the JEditorPane designed especially for the editing (and 
display) of styled text. It differs from the JEditorPane only in its manner of providing the content to 
display because the text isn't tagged with the styles as it would be in an HTML or RTF document. 

The JTextPane relies on three interfaces for the setting of text attributes: AttributeSet for 
a basic collection of attributes, MutableAttributeSet for a changeable collection of attributes, 
and Style for a set of attributes to be associated with a part of a StyledDocument. 

This section will introduce JTextPane. See Chapter 16 for additional information about 
configuring styles for different parts of the styled content within a JTextPane. 


Creating a JTextPane 


There are only two constructors for JTextPane: 


public JTextPane() 
JTextPane textPane = new JTextPane(); 
JScrollPane scrollPane = new JScrollPane(textPane); 


public JTextPane(StyledDocument document) 
StyledDocument document = new DefaultStyledDocument(); 
JTextPane textPane = new JTextPane(document); 
JScrollPane scrollPane = new JScrollPane(textPane); 


The no-argument constructor initially has zero contents. The second constructor allows 
you to create the Document first, and then use itin the JTextPane. 


Tip Remember to place your JTextPane within a JScrol11Pane if the contents will be larger than the 
available screen space. 


JTextPane Properties 


Table 15-14 shows the eight properties of JTextPane. You'll look at these in greater detail in 
Chapter 16. 


Table 15-14. JTextPane Properties 


Property Name Data Type Access 
characterAttributes AttributeSet Read-only 
document Document Write-only bound 


editorKit EditorKit Write-only bound 
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Table 15-14. JTextPane Properties (Continued) 


Property Name 


inputAttr 
logicalSt 
paragraph 
styledDoc 
UIClassID 


ibutes 
yle 
Attributes 


ument 


Data Type Access 
MutableAttributeSet Read-only 
Read-write 
AttributeSet Read-only 
StyledDocument Read-write* 
Read-only 


* Changing the styledDocument property triggers a bound property notification on the document property. 


Customizing a JTextPane Look and Feel 


The JTextPane is asubclass ofa JEditorPane. It has the same appearance under all the predefined 
look and feel types as the JTextArea (see Figure 15-18). Although the contents might differ, the 
look and feel is the same. 

The available set ofUIResource-related properties for a JTextPane is shown in Table 15-15. 
For the JTextPane component, there are 15 different properties. Their names are similar to the 
JTextArea settings. 


Table 15-15. JTextPane UlResource Elements 


Property String 


TextPane. 
TextPane 
TextPane. 
TextPane 
TextPane. 
TextPane. 
TextPane. 
TextPane. 
TextPane. 
TextPane. 
TextPane. 
TextPane. 
TextPane. 


TextPane. 


TextPaneU 


actionMap 


«background 


border 


.CaretAspectRatio 


caretBlinkRate 
caretForeground 
focusInputMap 

font 

foreground 
inactiveForeground 
keyBindings 

margin 
selectionBackground 
selectionForeground 


1 


Object Type 
ActionMap 
Color 
Border 
Number 
Integer 
Color 
InputMap 
Font 

Color 
Color 
KeyBinding[ ] 
Insets 
Color 
Color 


String 
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Loading a JTextPane with Content 


Listing 15-17 provides an example that loads the content for a StyledDocument for a JTextPane. 
This is just to give you an idea of the possibilities. The details of using Style, SimpleAttributeSet, 
and StyleConstants will be discussed in Chapter 16. 


Listing 15-17. JTextPane Example 


import javax.swing.*; 
import javax.swing.text.*; 
import javax.swing.event.*; 
import java.awt.*; 


public class TextPaneSample ( 

private static String message = 
"In the beginning, there was COBOL, then there was FORTRAN, " + 
"then there was BASIC, ... and now there is Java.Wn”; 


public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("TextPane Example"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


StyleContext context = new StyleContext(); 
StyledDocument document = new DefaultStyledDocument (context); 


Style style = context.getStyle(StyleContext.DEFAULT_STYLE); 
StyleConstants.setAlignment(style, StyleConstants.ALIGN_RIGHT); 
StyleConstants.setFontSize(style, 14); 
StyleConstants.setSpaceAbove(style, 4); 
StyleConstants.setSpaceBelow(style, 4); 


// Insert content 
try ( 
document .insertString(document.getlength(), message, style); 
) catch (BadLocationException badLocationException) f 
System.err.println("0ops"); 
J 


SimpleAttributeSet attributes = new SimpleAttributeSet(); 
StyleConstants.setBold(attributes, true); 
StyleConstants.setlItalic(attributes, true); 


// Insert content 


try ( 
document .insertString(document.getlength(), "Hello Java", attributes); 
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j catch (BadLocationException badLocationException) ( 
System.err.println("0ops"); 
y 


// Third style for icon/component 
Style labelStyle = context.getStyle(StyleContext.DEFAULT_STYLE); 


Icon icon = new Imagelcon("Computer.gif"); 
JLabel label = new JLabel(icon); 
StyleConstants.setComponent(labelStyle, label); 


// Insert content 
try ( 
document .insertString(document.getlength(), "Ignored", labelStyle); 
$ catch (BadLocationException badLocationException) ( 
System.err.println("0ops"); 
E 


JTextPane textPane = new JTextPane(document)'; 
textPane.setEditable(false); 

JScrollPane scrollPane = new JScrollPane(textPane); 
frame.add(scrollPane, BorderLayout.CENTER); 


frame.setSize(300, 150); 
frame.setVisible(true); 
A 
5 
EventQueue.invokeLater(runner); 
) 
) 


The key line of the source code is the call to insertString() and its style argument: 
document .insertString(document.getLength(), message, style); 


Figure 15-20 shows how a JTextPane might look like with a few paragraphs of content. 
Notice that the content is not restricted to just text; it can have images as well. 


o rearanecamae A 


In the beginning, there was COBOL, then 
there was FORTRAN, then there was 
BASIC, ... and now there is Java 


Helio Java] 


Figure 15-20. Sample JTextPane 
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Summary 


In this chapter, you began to explore the details of the Swing text components. You initially 
looked at the root text component, JTextComponent, and the many operations it defines for 
all other text components. You then explored the specific text components of JTextField, 
JPasswordField, JFormattedTextField, JTextArea, JEditorPane, and JTextPane. 

You also explored the various pieces that make up the different components. You delved 
into the data model for the text components, based on the Document interface, for the 
AbstractDocument and PlainDocument classes. You also looked at creating a custom document 
filter via Document Filter for restricting input to a text component. In addition, you explored the 
Caret and Highlighter interfaces for displaying the cursor and highlighted text, the 
NavigationFilter for limiting movement within the text component, as well as the Keymap to 
make the text component act as the controller. As the controller, the Keymap converts a user's 
keystrokes into specific actions that affect the model for the text component. 

You also looked at how events are handled within the Swing text components. In addition 
to the basic AWT event handling classes, Swing adds some new ones designed for listening 
for cursor movement with the CaretListener and document content changes with the 
DocumentListener. The JEditorPane also provides another event handler with the 
HyperlinkListener. And there is the general Swing support for input verification through 
InputVerifier. 

In Chapter 16, you'll further explore the Swing text components. This chapter touched on 
the basic features of all the components, while the next chapter goes into all the gory details of 
working with the TextAction, formatting input for a JFormattedTextField, and configuring 
Style objects to work with a StyledDocument. You”1l also look into shuffling through the tags 
of your HTMLDocument. 


CHAPTER 16 


Advanced Text Capabilities 


l. Chapter 15, you were introduced to the myriad capabilities ofthe Swing text components. 
In this chapter, you'll continue on the same path by looking at some advanced capabilities that 
will prove useful in special situations. 

The Swing text components ship with many prefabricated features. For instance, as you 
saw in Chapter 15, although text components have methods such as cut (), copy(), and paste() 
to work with the system clipboard, you really don't need to use them. This is because the Swing 
text components come with their own predefined set of Action objects, which you'll explore in 
this chapter. To use Action objects, just attach them to a component, such as a button or menu 
item, and then simply select the component that triggers the Action. For text components, the 
Action object is an instance of TextAction, which has a nice additional feature of knowing 
which text component last had the input focus. 

In this chapter, you'll also look at how to create stylized text for display in a JTextPane. 

If you want to display multicolored text documents or different font styles, the JTextPane 
component provides a series of interfaces and classes to describe the attributes attached to 
the document. The AttributeSet interface gives you these on a read-only basis, and the 
MutableAttributeSet interface extends AttributeSet in order to set attributes. You'll see how 
the SimpleAttributeSet class implements both of these interfaces by offering a Hashtable to 
store the text attributes, and how the StyleConstants class helps to configure the many text 
attributes you can apply. And, you'll learn how to work with tab stops within your text documents, 
including how to define leader characters and how text is aligned. 

Next, you'll get a glimpse of the different editor kits that Swing provides, focusing on the 
inner workings of the HTMLDocument. When the JEditorPane displays HTML, the HTMLEditorKit 
controls how to load and display the HTML content into an HTMLDocument. You'1l see how the 
parser loads the content and how to iterate through the different tags in the document. 

Lastly, you'll learn how to take advantage of the formatted input options and validation 
available with the JFormattedTextField component. You”1l see how to provide for formatted 
dates and numbers, as well as masked input like telephone and social security numbers. 


Using Actions with Text Components 


The TextAction class is a special case ofthe Action interface that was defined with the other 
Swing event-handling capabilities in Chapter 2 and briefly reviewed in Chapter 15. The purpose 
ofthe TextAction class is to provide concrete Action implementations that can work with text 
components. These implementations are smart enough to know which text component most 
recently had the input focus and therefore should be the subject of the action. 
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For every text component, you need a way to associate keystrokes with specific actions. 
This is done via the Keymap interface, which maps a KeyStroke to a TextAction, so that separate 
KeyListener objects don't need to be associated with the text component for each keystroke in 
order to listen for it. Key maps can be shared across multiple components and/or customized 
for a particular look and feel. The JTextComponent also has getKeymap() and setKeymap() methods 
that allow you to read or customize the key map. 


Note Although the Swing text components use TextAction, KeyStroke, and Keymap, they still support 
the ability to attach a KeyListener. Using a KeyListener, however, usually isn't appropriate, especially 
when you want to restrict input to match certain criteria. The better approach for restricting input is to come 
up with a custom Document Filter, as demonstrated in Chapter 15, or use an InputVerifier. In addition, 
the actual Keymap implementation is just a wrapper to the InputMap/ActionMap combination used for 
keyboard-action mapping in the nontextual Swing components. 


The text components come with many predefined TextAction implementations. Through 
a default key map, the text components know about these predefined actions, so they know 
how to insert and remove content, as well as how to track the positions of both the cursor and 
caret. If the text component supports stylized content, as JTextPane does, there are additional 
default actions to support this content. All these implementations derive from the JFC/Swing 
technology editor kits. As discussed in the “The Editor Kits” section later in this chapter, an 
editor kit provides a logical grouping of the various ways to edita specific type of text component. 


Listing Actions 


To find out which actions a JTextComponent supports, you merely ask by using the public 
Action[ ] getActions() method. This will return an array of Action objects, usually of type 
TextAction, that can be used like any other Action, such as for creating buttons on a JToo1Bar. 

Figure 16-1 shows a program that will list the actions for the different predefined components. 
Pick a component from the JRadioButton group, and its list of text actions will be displayed in 
the text area. For each action, the program shows the action name and class name. 


lalx 

Pick to List Actions Count 54 a 
E beep: javax.swing.text DefaultEditorkit$! 

(9) JTextField caretbackward Frac sngtenDetad 
caret-begin : javax.swing.textDefaultEdit 


O JFormattedTextField caretbegin-line : javax.swing.text. Default 
caret-begin-paragraph : javax.swing.text 


(0 JPasswordField caretbegin-word : javax.swing.text.Defau 
a caret-down : javax.swing.text DefaultEdita 
U JTextArea caret-end : javax.swing.text DefaultEditor! 
"y caretend-line : javax.swing.text.DefaultE 
U JTextPane caretend-paragraph : javax.swing.text.De 


caretend-word : javax.swing.text DefaultB 


O JEditorPane lcar 
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Figure 16-1. TextAction list demonstration 
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The same set of 53 actions is available for all text components. JTextField, 
JFormattedTextField, and JPasswordField have one extra action, called notify-field-accept, 
used for detecting when the Enter key is pressed while in the text component. The 
JFormattedTextField has a second extra action, reset-field-edit, for when the contents don't 
validate against the provided format mask. JTextPane adds its own set of about 20 more actions 
for dealing with multiple-attributed text. 

Listing 16-1 shows the source used to generate Figure 16-1. The RadioButtonUtils class 
was created in Chapter 5. 


Listing 16-1. Listing Text Component Actions 


import javax.swing.*; 
import javax.swing.text.*; 
import java.awt.*; 

import java.awt.event.*; 
import java.io.*; 

import java.util.*; 


public class ListActions ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() 4 
public void run() £ 
JFrame frame = new JFrame("TextAction List"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


String components[] = ( 
"JTextField", "JFormattedTextField", "JPasswordField", 
"JTextArea", "JTextPane", "JEditorPane"); 


final JTextArea textArea = new JTextArea(); 
textArea.setEditable(false); 

JScrollPane scrollPane = new JScrollPane(textArea); 
frame.add(scrollPane, BorderLayout.CENTER); 


ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 

// Determine which component selected 

String command = actionEvent.getActionCommand(); 

JTextComponent component = null; 

if (command.equals("JTextField")) £ 
component = new JTextField(); 

j else if (command.equals("JFormattedTextField")) £ 
component = new JFormattedTextField(); 

j else if (command.equals("JPasswordField")) £ 
component = new JPasswordField(); 
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) else if (command.equals("JTextArea")) ( 
component = new JTextArea(); 

) else if (command.equals("JTextPane")) £ 
component = new JTextPane(); 

y else £ 
component = new JEditorPane(); 


) 


// Process action list 
Action actions[] = component .getActions(); 
// Define comparator to sort actions 
Comparator<Action> comparator = new Comparator<Action>() ( 
public int compare(Action a1, Action a2) [ 
String firstName = (String)a1.getValue(Action.NAME); 
String secondName = (String)a2.getValue(Action.NAME); 
return firstName.compareTo(secondName); 
) 
E 
Arrays.sort(actions, comparator); 
StringWriter sw = new StringWriter(); 
PrintWriter pw = new PrintWriter(sw, true); 
int count = actions. length; 
pw.println("Count: " + count); 
for (int i=0; i<count; i++) ( 
pw.print (actions[i].getValue(Action.NAME)); 
pw.print (" : "); 
pw.printin(actions[i].getClass().getName()); 
J 
pw.close(); 
textArea.setText(sw.toString()); 
textArea.setCaretPosition(0); 
y 
5 


final Container componentsContainer = 
RadioButtonUtils.createRadioButtonGrouping(components, 
"Pick to List Actions", actionListener); 


frame.add(componentsContainer, BorderLayout.WEST); 
frame.setSize(400, 250); 
frame.setVisible(true); 
) 
5 
EventQueue.invokeLater(runner); 
J 
) 
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Using Actions 


So far, you've seen that there are many predefined TextAction implementations available 

for the various text components, but you haven't used any of them. By making a few minor 
changes to Listing 16-1, you can enhance the program in order to activate it. The modified 
program is shown in Listing 16-2. With this version, when one of the radio buttons is selected, 
that type of text component will be displayed where the text list of Action objects appears in 
Figure 16-1. In addition, the different Action objects are added to a new JMenuBar placed at the 
top of the display window. 


Note In the program shown in Listing 16-2, after all the menu buttons are activated, you're stuck with 
a text label that might not be exactly what you want. However, you can easily change this with the public 
void setText(String label) method of JMenulten. If you do this, remember that you need to know 
what's in the menu item to change the label to something meaningful. 


Listing 16-2. Enabling Text Component Actions 


import javax.swing.*; 
import javax.swing.text.*; 
import java.awt.*; 

import java.awt.event.*; 
import java.io.*; 

import java.util.*; 


public class ActionsMenuBar ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() £ 
public void run() £ 

final JFrame frame = new JFrame("TextAction Usage"); 
frame.setDefaultClose0peration(JFrame.EXIT_ON CLOSE); 
final JscrollPane scrollPane = new JScrollPane(); 
frame.add(scrollPane, BorderLayout.CENTER); 


final JMenuBar menuBar = new JMenuBar(); 
frame .setJMenuBar (menuBar) ; 


ActionListener actionListener = new ActionListener() ( 
JTextComponent component; 
public void actionPerformed(ActionEvent actionEvent) ( 
// Determine which component selected 
String command = actionEvent.getActionCommand(); 
if (command.equals("JTextField")) £ 
component = new JTextField(); 
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J 


J 


5 


J 


) else if (command.equals("JFormattedTextField")) f 


component = new JFormattedTextField(); 

) else if (command.equals("JPasswordField")) ( 
component = new JPasswordField(); 

) else if (command.equals("JTextArea")) ( 
component = new JTextArea(); 

) else if (command.equals("JTextPane")) £ 
component = new JTextPane(); 

y else [ 
component = new JEditorPane(); 

) 

scrollPane.setViewportView(component); 

// Process action list 

Action actions[] = component .getActions(); 

menuBar.removeA11(); 

menuBar.revalidate(); 

JMenu menu = null; 

for (int i=0, n=actions.length; i<n; i++) ( 
if ((1% 10) == 0) [ 

menu = new JMenu("From 
menuBar.add(menu) ; 


" 


+ 1); 


) 
menu.add(actions[i]); 
) 
menuBar.revalidate(); 


) 
18 


String components[] = ( 


"JTextField", "JFormattedTextField”, "JPasswordField”, 


"JTextArea", "JTextPane", "JEditorPane"); 
final Container componentsContainer = 


RadioButtonUtils.createRadioButtonGrouping(components, 


"Pick to List Actions", actionListener); 
frame.add(componentsContainer, BorderLayout.WEST); 


frame.setSize(400, 300); 
frame.setVisible(true); 


Event0Queue.invokeLater(runner); 
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Figure 16-2 shows some of the available operations for a JTextArea. When you select the 
different menu options, the JTextComponent is appropriately affected. 
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Figure 16-2. TextAction list usage demonstration 


This technique is useful because it shows that you can readily discover the supported 
operations of a text component and provide access to that behavior without knowing precisely 
what the actual behavior is. This is just one demonstration of the many ways you can use 
TextAction objects. 


Finding Actions 


Although listing and using Action objects related to a text components a fairly malleable 
process, unless you know what you're looking for, it isn't very useful. Thankfully, the 
DefaultEditorKit has 46 class constants that match many of the shared 46 (out of 53) Action 
objects of all the text components. The class constants' names more or less reflect their function- 
ality. The JTextField adds an additional constant for the Action shared with JFormattedTextField 
and JPasswordField. Unfortunately, the names associated with the extra actions available to 
the JTextPane aren't class constants of any text component and are just used internally within 
the StyledEditorKit, where you will find the additional Action implementations defined. 


Note One additional Action exists primarily for debugging purposes. lts Action name is dump-model, 
and it lacks a class constant to go with it. When initiated, the method literally dumps out the Document model 


Element structure for the text component. 


Table 16-1 lists the 47 constants available to help you locate the predefined Action you're 
seeking. 
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Table 16-1. TextAction Name Constants 
DefaultEditorKit.backwardAction 

DefaultEditorKit.beepAction 
DefaultEditorKit.beginAction 
DefaultEditorKit.beginLineAction 
DefaultEditorKit.beginParagraphAction 
DefaultEditorKit.beginWordAction 
DefaultEditorKit.copyAction 
DefaultEditorKit.cutAction 
Defaul 
DefaultEditorKit.deleteNextCharAction 


DefaultEditorKit.deletePrevCharAction 


DefaultEditorKit.downAction 


DefaultEditorKit.endLineAction 
DefaultEditorKit.endParagraphAction 
DefaultEditorKit.endWordAction 
DefaultEditorKit.forwardAction 
DefaultEditorKit.insertBreakAction 
DefaultEditorKit.insertContentAction 
DefaultEditorKit.insertTabAction 
DefaultEditorKit.nextWordAction 


DefaultEditorKit.pageDownAction 


DefaultEditorKit.pageUpAction 
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DefaultEditorKit.pasteAction 


EditorKit.defaultKeyTypedAction 
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DefaultEditor 


DefaultEditorKi 
DefaultEditorKi 
DefaultEditorKi 
DefaultEditorKi 
DefaultEditorKi 
DefaultEditorKi 
DefaultEditorKi 
DefaultEditorKi 
DefaultEditorKi 
DefaultEditorKi 
DefaultEditorKi 
DefaultEditorKi 
DefaultEditorKi 
DefaultEditorKi 
DefaultEditorKi 
DefaultEditorKi 
DefaultEditorKi 
DefaultEditorKi 
DefaultEditorKi 
DefaultEditorKi 
DefaultEditorKi 


.previousWordAction 
.TeadOnlyAction 
.selectAllAction 
.selectionBackwardAction 
.selectionBeginAction 
.selectionBeginLineAction 
.selectionBeginParagraphAction 
.selectionBeginWordAction 
.selectionDownAction 
.selectionEndAction 
.selectionEndLineAction 
.selectionEndParagraphAction 
.selectionEndWordAction 
.selectionForwardAction 
.selectionNextWordAction 
.selectionPreviousWordAction 
.selectionUpAction 
.selectLineAction 
.selectParagraphAction 
.selectWordAction 

.UpAction 


.writableAction 


JTextField.notifyAction 


With such a huge list of constants, what on earth do you do with them? Well, first you find 
the constant for the predefined TextAction you want to use (or learn the necessary text string if 
no constant is provided). This is relatively easy because the names are fairly self-explanatory. 

To demonstrate, Listing 16-3 contains a program that shows howto work with these constants. 
The program has two text areas to show that TextAction objects really know to work with the 
last text component that had the input focus. One set of menu items includes two options 
that are used to switch the text area from read-only to writable. This action is done using the 
DefaultEditorKit.readOnlyAction and DefaultEditorKit.writableAction names. The other 
set of menu items includes options for cut, copy, and paste support, whose constants are 
DefaultEditorKit.cutAction, DefaultEditorKit.copyAction, and DefaultEditorKit.pasteAction 
Because the constants are String values, you need to look up the actual Action object to use. 
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The lookup process requires getting the ActionMap for the component with getActionMap(), 
and then searching for the key with the get() method of ActionMap, as in this example: 


Action readAction = component .getActionMap().get(DefaultEditorKit.read0nlyAction); 


Listing 16-3. Using Text Component Actions 


import javax.swing.*; 
import javax.swing.text.*; 
import java.awt.*; 

import java.awt.event.*; 
import java.io.*; 

import java.util.*; 


public class UseActions ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() 4 
public void run() £ 
JFrame frame = new JFrame("Use TextAction"); 
frame.setDefaultClose0peration(JFrame.EXIT_ON CLOSE); 
Dimension empty = new Dimension(0,0); 


final JTextArea leftArea = new JTextArea(); 
JScrollPane leftScrollPane = new JScrollPane(leftArea); 
leftScrollPane.setPreferredSize(empty); 


final JTextArea rightArea = new JTextArea(); 
JScrollPane rightScrollPane = new JScrollPane(rightArea); 
rightScrollPane.setPreferredSize(empty); 


JSplitPane splitPane = new JSplitPane(ISplitPane.HORIZONTAL SPLIT, 
leftScrollPane, rightScrollPane); 


JMenuBar menuBar = new JMenuBar(); 
frame .setJMenuBar (menuBar) ; 

JMenu menu = new JMenu("Options"); 
menuBar.add(menu) ; 

JMenultem menultem; 


Action readAction = 
leftArea.getActionMap().get(DefaultEditorKit.readOnlyAction); 

menultem = menu.add(readAction); 

menultem.setText("Make read-only"); 

Action writeAction = 
leftArea.getActionMap().get(DefaultEditorKit.writableAction); 

menultem = menu.add(writeAction); 

menuTtem.setText("Make writable"); 
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menu.addSeparator(); 


Action cutAction = 
leftArea.getActionMap().get(DefaultEditorKit.cutAction); 

menultem = menu.add(cutAction); 

menulItem.setText("Cut"); 

Action copyAction = 
leftArea.getActionMap().get(DefaultEditorKit.copyAction); 

menultem = menu.add(copyAction); 

menultem.setText ("Copy"); 

Action pasteAction = 
leftArea.getActionMap().get(DefaultEditorKit.pasteAction); 

menultem = menu.add(pasteAction); 

menultem.setText("Paste"); 


frame.add(splitPane, BorderLayout.CENTER); 
frame.setSize(400, 250); 
frame.setVisible(true); 
splitPane.setDividerLocation(.5); 
J 
$5 
EventQueue.invokeLater(runner); 
) 
J 


Figure 16-3 shows the program at work. Notice that for each JMenuTtem created, the text 
label changes to give it a more user-friendly setting. 
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Figure 16-3. Specific TextAction usage demonstration 


By asking for specific TextAction instances, you don't need to constantly recode repetitive 
operations. In fact, ifyou constantly find yourself repeating the same operations over and over 
with a text component, it's probably time for you to create your own TextAction objects. 
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Creating Styled Text 


In Chapter 15, you looked at displaying plain text and HTML. With the Swing text components— 
or at least the JTextPane—you can also display stylized text, in which different blocks of text 
can have multiple attributes. These attributes might include boldface, italics, a different font 
or color at the character level, or justification at the paragraph level, just as with any ofthe 
modern word processors. 

To support these capabilities, Swing supplies many different interfaces and classes, all of 
which start with the specialized Document interface extension of StyledDocument. The Document 
interface was introduced in Chapter 15, focusing on the PlainDocument implementation class. 
The StyledDocument interface, or more precisely, the DefaultStyledDocument implementation, 
manages a series of styles and attribute sets for the contents of a Document. 

The various styles used by a StyledDocument are described initially by the AttributeSet 
interface, which is a set of key/value pairs of read-only attributes. The key for an attribute 
might be “current font,” in which the setting would be the font to use. To actually change the 
font, you need to move on to the MutableAttributeSet interface, which supplies the ability to 
add and remove attributes. For instance, if you had an AttributeSet for “bold,” you could use 
MutableAttributeSet to also add italics, underlining, or colorization (or all three) to the set. 

For a simple implementation of Attributeset, there is the StyleContext.'SmallAttributeSet 
class, which uses an array to manage the set of attributes. For an implementation of the 
MutableAttributeSet interface, there is the SimpleAttributeSet class, which uses a Hashtable 
to manage the attributes. More complex attribute sets move on to the Style interface, which 
adds a name to the set of attributes as defined by a MutableAttributeSet. The actual Style 
implementation class is the StyleContext.NamedStyle class. Besides adding a name, the Style 
interface adds the ability to have a ChangeListener monitor a set of attributes for changes. 

The class that manages the set of Style objects for a StyledDocument is the StyleContext 
class. An implementation of the AbstractDocument.AttributeContext interface, StyleContext 
uses the StyleConstants class, which defines various attributes for commonly used styles. 
When working with HTML documents, the StyleContext is actually a StyleSheet, which may 
help you in understanding the whole arrangement. Keep in mind that all of the classes and 
interfaces discussed here (except StyleSheet) are required just to set up the Document data 
model for a particular JTextPane. 


StyledDocument Interface and DefaultStyledDocument Class 


The StyledDocument interface extends the Document interface by adding the ability to store 
styles for the content of the document. These styles can describe the character or paragraph 
attributes, such as color, orientation, or font. 


public interface StyledDocument extends Document ( 
public Style addStyle(String nm, Style parent); 
public Color getBackground(AttributeSet attribute); 
public Element getCharacterElement(int position); 
public Font getFont(AttributeSet attribute); 
public Color getForeground(AttributeSet attribute); 
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public Style getLogicalStyle(int position); 

public Element getParagraphElement(int position); 

public Style getStyle(String name); 

public void removeStyle(String name); 

public void setCharacterAttributes(int offset, int length, AttributeSet s, 
boolean replace); 

public void setLogicalStyle(int position, Style style); 

public void setParagraphAttributes(int offset, int length, AttributeSet s, 
boolean replace); 


The DefaultStyledDocument class is the implementation of the StyledDocument interface 
provided with the Swing components. It serves as the data model for the JTextPane component. 


Creating a DefaultStyledDocument 


You can create a DefaultStyledDocument in any one of the three ways listed here: 


public DefaultStyledDocument() 
DefaultStyledDocument document = new DefaultStyledDocument (); 


public DefaultStyledDocument(StyleContext styles) 
StyleContext context = new StyleContext(); 
DefaultStyledDocument document = new DefaultStyledDocument (context); 


public DefaultStyledDocument(AbstractDocument.Content content, StyleContext styles) 
AbstractDocument.Content content = new StringContent(); 
DefaultStyledDocument document = new DefaultStyledDocument (content, context); 


You can share the StyleContext between multiple documents or use the default context. 
In addition, you can predefine the content using one ofthe AbstractDocument . Content imple- 
mentations, either GapContent or StringContent. Itis the responsibility of one of these Content 
implementations to store the actual Document content. 


DefaultStyledDocument Properties 


Besides having a default root element to describe the contents of the document, the 
DefaultStyledDocument makes available the style names as an Enumeration. These are the only 
two properties defined at the DefaultStyledDocument level, as shown in Table 16-2. There are 
other properties you can get for a DefaultStyledDocument; however, they require the position 
or AttributeSet from which to get them. 


Table 16-2. DefaultStyledDocument Properties 


Property Name Data Type Access 
defaultRootElement Element Read-only 


styleNames Enumeration Read-only 
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AttributeSet Interface 


The AttributeSet interface describes a read-only set of key/value attributes, allowing you 
access to the descriptive content of a series of attributes. Ifthe set of attributes lacks a specific 
key defined forit, the AttributeSet supports the ability to look elsewhere by traveling up a chain 
to a resolving parent for the parent's definition ofthe attribute. This allows the AttributeSet to 
define a core set of attributes and lets developers (or possibly even users) modify only the set of 
attributes they want to change. Unless you want someone to change the defaults globally, you 
shouldn't provide direct access to the resolving parent. That way, you never lose any of the 
original settings. 


public interface AttributeSet ( 
// Constants 
public final static Object NameAttribute; 
public final static Object ResolveAttribute; 
// Properties 
public int getAttributeCount(); 
public Enumeration getAttributeNames(); 
public AttributeSet getResolveParent(); 
// Other methods 
public boolean containsAttribute(Object name, Object value); 
public boolean containsAttributes(AttributeSet attributes); 
public AttributeSet copyAttributes(); 
public Object getAttribute(Object key); 
public boolean isDefined(Object attrName); 
public boolean isEqual(AttributeSet attr); 


MutableAttributeSet Interface 


The MutableAttributeSet interface describes how you would go about adding to or removing 
from the set of attributes, as well as how to set the resolving parent. 


public interface MutableAttributeSet extends AttributeSet ( 
public void addAttribute(Object name, Object value); 
public void addAttributes(AttributeSet attributes); 
public void removeAttribute(Object name); 
public void removeAttributes(AttributeSet attributes); 
public void removeAttributes(Enumeration names); 
public void setResolveParent(AttributeSet parent); 


SimpleAttributeSet Class 


The SimpleAttributeSet class is the first implementation of the AttributeSet interface. When 
you begin using it, you'll finally be able to see just how to create the multiple-attributed text 
for display in the JTextPane. The SimpleAttributeSet class is a specific implementation of 
AttributeSet that relies on a standard Hashtable for managing the key/attribute pairs. 
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Creating a SimpleAttributeSet 


SimpleAttributeSet has two constructors: 


public SimpleAttributeSet() 
SimpleAttributeSet attributeSet1 = new SimpleAttributeSet(); 


public SimpleAttributeSet(AttributeSet source) 
SimpleAttributeSet attributeSet2 = new SimpleAttributeSet(attributeSet1); 


You would typically create an empty SimpleAttributeSet, and then set its attributes, as 
in the first constructor listed. Or, you can instead provide the initial settings for the set of 
attributes in the constructor. Note that this is not the resolving parent—it's just an initialized 
data structure. 


SimpleAttributeSet Properties 


Table 16-3 displays the four properties of SimpleAttributeSet. They provide access to the set of 
attributes, let you know whether any attributes exist, and identify the resolving parent (ifany). 


Table 16-3. SimpleAttributeSet Properties 


Property Name Data Type Access 
attributeCount int Read-only 
attributeNames Enumeration Read-only 
empty boolean Read-only 
resolveParent AttributeSet Read-write 
Using a SimpleAttributeSet 


To create an appropriate AttributeSet to use with a SimpleAttributeSet, you need to discover 
the keys for the attributes you want to alter. You'll see some helper methods shortly in the 
StyleConstants class covered in the next section. All the keys are hidden away in four public 
inner classes of StyleConstants: CharacterConstants, ColorConstants, FontConstants, and 
ParagraphConstants, as shown in Table 16-4. 


Table 16-4. Key Constants for Storing AttributeSet Values 


AttributeSet Key Constants Value Type Default Setting 
CharacterConstants.Background Color Color. BLACK 
ColorConstants.Background Color Color. BLACK 
CharacterConstants.Bidilevel Integer 0 
CharacterConstants.Bold Boolean false 


FontConstants.Bold Boolean false 
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AttributeSet Key Constants Value Type Default Setting 
CharacterConstants.ComponentAttribute Component null 
CharacterConstants.Family String "Monospaced" 
FontConstants. Family String "Monospaced" 
CharacterConstants.Foreground Color Color. BLACK 
ColorConstants.Foreground Color Color. BLACK 
CharacterConstants.IconAttribute Icon null 
CharacterConstants.Italic Boolean false 
FontConstants.Italic Boolean false 
CharacterConstants.Size Integer 12 
FontConstants.Size Integer 12 
CharacterConstants.StrikeThrough Boolean false 
CharacterConstants.Subscript Boolean false 
CharacterConstants.Superscript Boolean false 
CharacterConstants.Underline Boolean false 
ParagraphConstants.Alignment Integer ALTGN_LEFT 
ParagraphConstants.FirstLineIndent Float 10) 
ParagraphConstants.LeftIndent Float 10) 
ParagraphConstants.LineSpacing Float 10) 
ParagraphConstants.Orientation unknown unknown 
ParagraphConstants.RightIndent Float 10) 
ParagraphConstants.SpaceAbove Float 10) 
ParagraphConstants.SpaceBelow Float 10) 
ParagraphConstants.TabSet TabSet null 


For example, to populate the StyledDocument for a JTextPane, after creating the 
DefaultStyledDocument, you add content to it by calling the public void insertString(int 
offset, String contents, AttributeSet attributes) method, which happens to throw a 
BadLocationException. You can then change the attribute set and add more attributes. So, if 
you wanted to create content that was both bold and italic, you would add two attributes to a 
SimpleAttributeSet and insert the content into the document: 


SimpleAttributeSet attributes = new SimpleAttributeSet(); 
attributes.addAttribute(StyleConstants.CharacterConstants.Bold, Boolean.TRUE); 
attributes.addAttribute(StyleConstants.CharacterConstants.Italic, Boolean.TRUE); 


599 


600 CHAPTER 16 ADVANCED TEXT CAPABILITIES 


// Insert content 
try ( 
document .insertString(document.getLength(), "Hello, Java", attributes); 
Y catch (BadLocationException badLocationException) ( 
System.err.println("0ops"); 
y 


Figure 16-4 shows how a JTextPane would appear with the words “Hello, Java” and a 
second insertion displayed. 


¿£ Simple Attributes 4 =10/x/ 


Hello, Java 


Figure 16-4. SimpleAttributeSet usage demonstration 
The source for the program shown in Figure 16-4 is presented in Listing 16-4. 


Listing 16-4. Using a SimpleAttributeSet 


import javax.swing.*; 
import javax.swing.text.*; 
import javax.swing.event.*; 
import java.awt.*; 


public class SimpleAttributeSample ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("Simple Attributes"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


StyledDocument document = new DefaultStyledDocument (>); 


SimpleAttributeSet attributes = new SimpleAttributeSet(); 

attributes.addAttribute(StyleConstants.CharacterConstants.Bold, 
Boolean. TRUE); 

attributes.addAttribute(StyleConstants.CharacterConstants.Italic, 
Boolean. TRUE); 
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// Insert content 
try ( 
document .insertString(document.getlength(), "Hello, Java", 
attributes); 
$ catch (BadLocationException badLocationException) ( 
System.err.println("Bad insert"); 


J 


attributes = new SimpleAttributeSet(); 

attributes.addAttribute(StyleConstants.CharacterConstants.Bold, 
Boolean. FALSE); 

attributes.addAttribute(StyleConstants.CharacterConstants.Italic, 
Boolean. FALSE); 

attributes.addAttribute(StyleConstants.CharacterConstants.Foreground, 
Color.LIGHT_GRAY); 


// Insert content 
try ( 
document .insertString(document.getlength(), 
" - Good-bye Visual Basic", attributes); 
$ catch (BadLocationException badLocationException) ( 
System.err.println("Bad insert"); 


J 


JTextPane textPane = new JTextPane(document)'; 
textPane.setEditable(false); 

JScrollPane scrollPane = new JScrollPane(textPane); 
frame.add(scrollPane, BorderLayout.CENTER); 


frame.setSize(300, 150); 
frame.setVisible(true); 
) 
5 
EventQueue.invokeLater(runner); 
) 
J 


In summary, to specify the style ofthe content, simply set up the attribute set, insert the 
content, and then repeat the steps for each bit of content you want to add. 


StyleConstants Class 


The StyleConstants class is chock-full of helper methods to simplify setting attribute sets. And 
you don't need to burrowinto the constants ofthe inner classes of StyleConstants, because the 
class makes them available through class constants at the StyleConstants level. 
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public static final Object Alignment; 

public static final Object Background; 

public static final Object BidiLevel; 

public static final Object Bold; 

public static final Object ComponentAttribute; 
public static final String ComponentElementName; 
public static final Object ComposedTextAttribute; 
public static final Object Family; 

public static final Object FirstLineIndent; 
public static final Object FontFamily; 

public static final Object FontSize; 

public static final Object Foreground; 

public static final Object IconAttribute; 
public static final String IconElementName; 
public static final Object Italic; 

public static final Object LeftIndent; 

public static final Object LineSpacing; 

public static final Object ModelAttribute; 
public static final Object NameAttribute; 
public static final Object Orientation; 

public static final Object ResolveAttribute; 
public static final Object RightIndent; 

public static final Object Size; 

public static final Object SpaceAbove; 

public static final Object SpaceBelow; 

public static final Object StrikeThrough; 
public static final Object Subscript; 

public static final Object Superscript; 

public static final Object TabSet; 

public static final Object Underline; 


Several static methods allow you to modify a MutableAttributeSet using more logical 
method names, without requiring you to know the more obscure AttributeSet name. Use the 
StyleConstants variables of ALIGN_ CENTER, ALIGN_JUSTIFIED, ALIGN_LEFT, and ALIGN_ RIGHT for 
the int argument to setAlignment (). The remaining settings are self-explanatory. 


public static void setAlignment(MutableAttributeSet a, int align); 
public static void setBackground(MutableAttributeSet a, Color fg); 
public static void setBidilevel(MutableAttributeSet a, int o); 
public static void setBold(MutableAttributeSet a, boolean b); 

public static void setComponent(MutableAttributeSet a, Component c); 
public static void setFirstlineIndent(MutableAttributeSet a, float 1); 
public static void setFontFamily(MutableAttributeSet a, String fam); 
public static void setFontSize(MutableAttributeSet a, int s); 

public static void setForeground(MutableAttributeSet a, Color fg); 
public static void setIcon(MutableAttributeSet a, Icon c); 

public static void setItalic(MutableAttributeSet a, boolean b); 
public static void setLeftIndent(MutableAttributeSet a, float 1); 
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public static void setlineSpacing(MutableAttributeSet a, float 1); 
public static void setRightIndent(MutableAttributeSet a, float 1); 
public static void setSpaceAbove(MutableAttributeSet a, float 1); 
public static void setSpaceBelow(MutableAttributeSet a, float 1); 
public static void setStrikeThrough(MutableAttributeSet a, boolean b); 
public static void setSubscript(MutableAttributeSet a, boolean b); 
public static void setSuperscript(MutableAttributeSet a, boolean b); 
public static void setTabSet(MutableAttributeSet a, TabSet tabs); 
public static void setUnderline(MutableAttributeSet a, boolean b); 


For instance, instead of calling the following to make the SimpleAttributeSet both bold 
and italic: 


attributes.addAttribute(StyleConstants.CharacterConstants.Bold, Boolean.TRUE) 
attributes.addAttribute(StyleConstants.CharacterConstants.Italic, Boolean.TRUE) 


you could use the following: 


StyleConstants.setBold(attributes, true); 
StyleConstants.setltalic(attributes, true); 


As you can see, the latter form is much more readable and easier to maintain! 


Tip Besides methods to change AttributeSet objects, the StyleConstants class provides many 
other methods that let you check the status of an AttributeSet to see if a setting is currently enabled 
or disabled. 


TabStop and TabSet Classes 


One of the key constants for storing AttributeSet values is the ParagraphConstants.TabSet 
attribute. The TabSet class represents a collection of TabStop objects, each defining a tab position, 
alignment, and leader. If you wanted to define your own tab stops for a JTextPane, you could 
create a set of TabStop objects, one for each tab stop, create the TabSet, and then associate the 
TabSet with a MutableAttributeSet. 


Creating a TabStop 


The TabStop class isn't a JavaBean component in the typical sense; it does not have a no-argument 
constructor. Instead, you must specify the position, in pixels, at which to place the tab stop. 
It has two constructors: 


public TabStop(float position) 
TabStop stop = new TabStop(40); 


public TabStop(float position, int align, int leader) 
TabStop stop = new TabStop(40, TabStop.ALIGN DECIMAL, TabStop.LEAD DOTS); 
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Note Although theoretically it can be specified, the leader argument to the TabStop constructor is 
currently ignored by the predefined text components. 


TabStop Properties 
Table 16-5 displays the three properties of TabStop, each initialized by the constructor. 


Table 16-5. TabStop Properties 


Property Name Data Type Access 

alignment int Read-only 
leader int Read-only 
position int Read-only 


Four alignment settings are specified by the five constants listed in Table 16-6. Figure 16-5 
shows how the different settings are displayed. 


Table 16-6. TabStop Alignment Settings 


Alignment Description 
ALTIGN_BAR Starts at tab position 
ALTGN_LEFT Starts at tab position 
ALTGN_CENTER Centers over tab position 
ALTGN_DECIMAL Places decimal point at tab position 
ALTGN_RIGHT Ends at tab position 
lol 
BAR 
CENTER 
3.14159265 


LEFT 
RIGHT 


Figure 16-5. TabStop alignment 


Note Although the ALIGN_BAR and ALIGN_LEFT are technically different constants, their alignment 
setting currently yields the same result. They are defined per the Rich Text Format (RTF) specification. 
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Using TabStop Objects 


Once you have a TabStop object, or a group ofthem, you pass the object to the TabSet constructor 
in an array of TabStop objects like this: 


TabSet tabset = new TabSet(new TabStop[] f[tabstop)) 


As an example, Listing 16-5 shows the source for the TabStop alignment program shown in 
Figure 16-5. 


Listing 16-5. Using Tabs 


import javax.swing.*; 
import javax.swing.text.*; 
import javax.swing.event.*; 
import java.awt.*; 


public class TabSample ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() £ 
public void run() £ 
JFrame frame = new JFrame("Tab Attributes"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


StyledDocument document = new DefaultStyledDocument(); 


int positions[] = (TabStop.ALIGN BAR, TabStop.ALIGN CENTER, 
TabStop.ALIGN DECIMAL, TabStop.ALIGN LEFT, TabStop.ALIGN RIGHT); 

String strings[] = ("WEBARAn", "WECENTERAn", "Xt3.141592651n", 
"MELEFTA A", "MERIGHTAN"); 


SimpleAttributeSet attributes = new SimpleAttributeSet(); 


for (int i=0, n=positions.length; i<n; i++) ( 

TabStop tabstop = new TabStop(150, positions[i], TabStop.LEAD DOTS); 

try ( 
int position = document .getLength(); 
document.insertString(position, strings[i], null); 
TabSet tabset = new TabSet(new TabStop[] ftabstop)); 
StyleConstants.setTabSet(attributes, tabset); 
document .setParagraphAttributes(position, 1, attributes, false); 

) catch (BadLocationException badLocationException) ( 
System.err.println("Bad Location"); 


605 


606 


CHAPTER 16 ADVANCED TEXT CAPABILITIES 


JTextPane textPane = new JTextPane(document); 
textPane.setEditable(false); 

JScrollPane scrollPane = new JScrollPane(textPane); 
frame.add(scrollPane, BorderLayout.CENTER); 


frame.setSize(300, 150); 
frame.setVisible(true); 
) 
5 
EventQueue.invokeLater(runner); 
) 
) 


In addition to specifying a position and alignment, you can specify which character you 
want to appear as a leader in the white space created by the tab character. By default, nothing 
exists there; therefore, the constantis LEAD_NONE. The other TabStop values create a line of 
periods (dots), equal signs, hyphens, thick lines, or underlines: LEAD_DOTS, LEAD_EQUALS, 
LEAD_HYPHENS, LEAD_THICKLINE, or LEAD_UNDERLINE. Unfortunately, this option is available but 
unsupported. While a nonstandard Swing component might support this capability, the standard 
ones currently do not support the different leader settings. 


Style Interface 


The Style interface is one more of the enhanced ways to specify an AttributeSet. It adds a 
name to the MutableAttributeSet and the ability to attach a ChangeListener to a Style in order 
to monitor changes to the attribute settings. For instance, you can configure a bold-italic style 
as shown here: 


String BOLD_ITALIC = "BoldlItalic"; 

Style style = (Style)document.getStyle(StyleContext.DEFAULT_STYLE); 
StyleConstants.setBold(style, true); 
StyleConstants.setlItalic(style, true); 

document .addStyle(BOLD_ITALIC, null); 


Later, you can attach the style to some text: 


style = document .getStyle(BOLD_ITALIC); 
document .insertString(document.getlength(), "Hello, Java", style); 


StyleContext Class 


The StyleContext class manages the styles for a styled document. With the help of the 
StyleContext.NamedStyle class, you can just let the JTextPane to do its own thing, because 
the StyleContext knows when something needs to be done. For HTML documents, the 
StyleContext is more specifically a StyleSheet. 
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The Editor Kits 


You briefly saw some of the default EditorKit capabilities of TextAction objects earlier in this 
chapter, in the “Using Actions with Text Components” section. The EditorKit class serves as 
the mastermind for pulling together all the different aspects of the text components. It creates 
documents, manages actions, and creates the visual representation ofthe document or View. 
In addition, an EditorKit knows how to read or write the document to a stream. Each document 
type requires its own EditorKit, so different ones are provided with the JEC/Project Swing 
components for both HTML and RTF text, as well as plain and styled text. 

The actual display of the Document contents is done through the EditorKit with the help of 
a ViewFactory. For each Element of the Document, the ViewFactory determines which View is 
created for that element and rendered by the text component delegate. For each different type 
of element, there is a different View subclass. 


Loading HTML Documents 


In Chapter 15, you saw how the read() and write() methods of the JTextComponent allow you 
to read in and write out content for a text component. While the LoadSave example from Listing 
15-3 in Chapter 15 demonstrated this process for the JTextField, it works with all the text 
components, as you would expect. The only requirement for making sure the loading and 
saving is done for the proper document type is to change the editor kit for the document. 

To demonstrate, here's how you could load an HTML file as a StyledDocument into a 
JEditorPane: 


JEditorPane editorPane = new JEditorPane(); 
editorPane.setEditorKit(new HTMLEditorKit()); 
reader = new FileReader(filename); 
editorPane.read(reader, filename); 


It is that easy. The content type of the component is set to be text/html and loads in the 
content from filename to be displayed as HTML content. One thing worth noting is that the 
loading is done asynchronously. 

If you need to load the content in synchronously, so that you can wait until everything is 
loaded, such as for parsing purposes, the process is a bit more involved. You need to work with 
the HTML parser (HTMLEditorKit.Parser class in javax.swing.text.html package), the parser 
delegator (ParserDelegator in the javax.swing.text.html.parser package), and the parser 
callback (HTMLEditorKit.ParserCallback) that you get from the HTMLDocument (as an 
HTMLDocument .HTMLReader). It sounds more complicated than it really is. To demonstrate, the 
following code loads a file synchronously into the JEditorPane. 


reader = new FileReader(filename); 

// First create empty empty HTMLDocument to read into 

HTMLEditorKit htmlKit = new HTMLEditorKit(); 

HTMLDocument htmlDoc = (HTMLDocument)htmlKit.createDefaultDocument(); 
// Next create the parser 

HTMLEditorKit.Parser parser = new ParserDelegator(); 

// Then get HTMLReader (parser callback) from document 
HTMLEditorKit.ParserCallback callback = htmlDoc.getReader(0); 
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// Finally load the reader into it 

// The final true argument says to ignore the character set 
parser.parse(reader, callback, true); 

// Examine contents 


Iterating Through HTML Documents 


After you have the HTML document loaded, in addition to just displaying the content inside a 
JEditorPane, you may find it necessary to parse through the content yourself to pull out various 
pieces. The HTMLDocument supports at least two manners of iteration through the content via 
the HTMLDocument. Iterator and Element Iterator classes. 


HTMLDocument.Iterator Class 


To use the HTMLDocument . Iterator, you ask an HTMLDocument to give you the iterator for a specific 
HTML. Tag. Then, for each instance of the tag in the document, you can look at the attributes of 
the tag. 

The HTML. Tag class includes 76 class constants for all the standard HTML tags (which the 
HTMLEditorKit understands), such as HTML. Tag.H1 for the <H1> tag. These constants are listed in 
Table 16-7. 


Table 16-7. HTML Tag Constants 


A DIR IMG SCRIPT 
ADDRESS DIV IMPLIED SELECT 
APPLET DL INPUT SMALL 
AREA DT ISINDEX SPAN 

B EM KBD STRIKE 
BASE FONT LI STRONG 
BASEFONT FORM LINK STYLE 
BIG FRAME MAP SUB 
BLOCKQUOTE FRAMESET MENU suP 
BODY H1 META TABLE 
BR H2 NOFRAMES TD 
CAPTION H3 OBJECT TEXTAREA 
CENTER H4 OL TH 
CITE H5 OPTION TITLE 
CODE H6 1 TR 
COMMENT HEAD PARAM TÍ 
CONTENT HR PRE Ú 

DD HTML S UL 


DFN I SAMP VAR 
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Note Only those HTML tag constants that have been previously flagged as a block tag—where the 
isBlock() method for the tag returns true—will work with the HTMLDocument . Iterator. For instance, 
STRONG is not a block tag, while H1 is. 


After you have the specific iterator to work with, you can look at the specific attributes and 
content of each instance of the tag through the help of the class properties shown in Table 16-8. 


Table 16-83. HTMLDocument.Iterator Properties 


Property Name Data Type Access 

attributes AttributeSet Read-only 
endOffset int Read-only 
startOffset int Read-only 
tag HTML.Tag Read-only 
valid boolean Read-only 


The other piece of the iteration process is the next() method, which lets you get the next 
instance of the tag in the document. The basic structure of using this iterator is as follows: 


// Get the iterator 
HTMLDocument.Iterator iterator = htmlDoc.getIterator(HTML.Tag.A); 


// For each valid one 
while (iterator.isValid()) f 


// Process element 


// Get the next one 
iterator.next(); 


J 


This can also be expressed in a basic for loop construct: 


for (HTMLDocument.Iterator iterator = htmlDoc.getIterator(HTML.Tag.A); 
iterator.isVvalid(); 
iterator.next()) f 
// Process element 


J 


Listing 16-6 demonstrates the use of HTMLDocument. Iterator. This program prompts you 
for a URL from the command line, loads the file synchronously, looks for all the <A> tags, and 
then displays all the anchors listed as HREF attributes. Think of this as a simple “spidering” 
application in which you can build up a database of URL links between documents. The start 
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and end offsets are also used to get the linking text. Just pass in the URL of the location you 
want to scan to run the program. 


Listing 16-6. Iterating Across HTML Documents for Links 


im 
im 
im 
im 
im 
im 
pu 


J 


J 


port java.io.*; 

port java.net.*; 

port javax.swing.*; 

port javax.swing.text.*; 

port javax.swing.text.html.*; 

port javax.swing.text.html.parser.*; 
blic class DocumentIteratorExample f 


public static void main(String args[]) throws Exception ( 


if (args.length != 1) ( 
System.err.println("Usage: java DocumentIteratorExample input-URL"); 


J 


// Load HTML file synchronously 

URL url = new URL(args[0]); 

URLConnection connection = url.openComnection(); 
InputStream is = connection.getInputStream(); 
InputStreamReader isr = new InputStreamReader (is); 
BufferedReader br = new BufferedReader (isr); 


HTMLEditorKit htmlKit = new HTMLEditorKit(); 

HTMLDocument htmlDoc = (HTMLDocument)htmlKit.createDefaultDocument (); 
HTMLEditorKit.Parser parser = new ParserDelegator(); 
HTMLEditorKit.ParserCallback callback = htmlDoc.getReader(0); 
parser.parse(br, callback, true); 


// Parse 

for (HTMLDocument.Iterator iterator = htmlDoc.getIterator(HTML.Tag.A); 
iterator.isVvalid(); 
iterator.next()) f 


AttributeSet attributes = iterator.getAttributes(); 

String srcString = (String)attributes.getAttribute(HTML.Attribute.HREF); 
System.out.print(srcString); 

int startOffset = iterator.getStartOffset(); 

int endOffset = iterator.getEnd0ffset(); 

int length = endOffset - startOffset; 

String text = htmlDoc.getText(startOffset, length); 

System.out.println(" - " + text); 


) 
System.exit(0); 


CHAPTER 16 ADVANCED TEXT CAPABILITIES 


Elementlterator Class 


Another way of examining the contents of an HTMLDocument is through the ElementIterator 
(which is not specific to HTML documents). When working with an ElementIterator, you basically 
see all the Element objects of the document and ask each one what itis. Ifthe object is some- 
thing you are interested in working with, you can get a closer look. 

To get the iterator for a document, just ask like this: 


ElementIterator iterator = new ElementIterator(htmlDoc); 


The Element Iterator is not meant to be a simple sequential iterator. Itis bidirectional with 
next () and previous () methods and supports going back to the beginning with first (). Although 
next () and previous() return the next or previous element to work with, you can also get the 
element at the current position by using current (). Here is the basic looping method through 
a document: 


Element element; 

ElementIterator iterator = new ElementIterator(htmlDoc); 
while ((element = iterator.next()) != null) ( 

// Process element 


) 


How do you find out which element you have in case you want to ignore itifit isn'tinter- 
esting? You need to get its name and type from its attribute set. 


AttributeSet attributes = element.getAttributes(); 
Object name = attributes.getAttribute(StyleConstants.NameAttribute); 
if (name instanceof HTML.Tag) ( 


Now you can look for specific tag types, such as HTML. Tag.H1, HTML. Tag.H2, and so on. The 
actual content for the tag would be in a child element of the element. To demonstrate, the 
following shows how to search for H1, H2, and H3 tags in a document, while displaying the 
appropriate titles associated with the tags. 


if ((name instanceof HTML.Tag) 88 ((name == HTML.Tag.H1) || 
(name == HTML.Tag.H2) || (name == HTML.Tag.H3))) 4 
// Build up content text as it may be within multiple elements 
StringBuffer text = new StringBuffer(); 
int count = element.getElementCount (); 
for (int i=0; i<count; i++) ( 
Element child = element.getElement(i); 
AttributeSet childAttributes = child.getAttributes(); 
if (childAttributes.getAttribute(StyleConstants.NameAttribute) == 
HTML.Tag.CONTENT) ( 
int start0ffset = child.getStart0ffset(); 
int endOffset = child.getEndOffset(); 
int length = endOffset - startOffset; 
text.append(htmlDoc.getText(startOffset, length)); 
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To try this out, you”! need to actually find a web page that uses H1, H2, or H3 tags. This 
isn't easy these days. Alternatively, you can just switch the H1, H2, and H3 to different tags that 
you know you will find. 


JFormattedTextField Formats 


In Chapter 15, you got a little taste ofthe JFormattedTextField component. Now, you'll get the 
rest ofthe meal. A JFormattedTextField is used for accepting formatted input from a user. This 
sounds simple, but is actually quite important and involved. Without a JFormattedTextField, 
getting formatted input isn't as easy as it sounds. Throwing in localization requirements makes 
life really interesting. 

Not only does the JFormattedTextField component support entering input in a formatted 
fashion, but it also allows the user to use the keyboard to increment and decrement the input 
value; for example, to scroll through the available months in a date. 

For a JFormattedTextField, the validation magic is controlled by the focusLostBehavior 
property. This can be set to one of four values: 


+ COMMIT_OR_REVERT: This is the default. When the component loses focus, the component 
automatically calls the commitEdit() method internally. This will parse the component's 
contents and throw a ParseException on error, reverting the contents to the most recent 
valid value. 


+ COMMIT: This setting is similar to COMMIT_OR_REVERT, butit leaves the invalid contents 
within the field, allowing the user to modify the setting. 


+ REVERT: This setting always reverts the value. 


+ PERSIST: This setting essentially does nothing. When the focusLostBehavior property is 
set to PERSIST, you should manually call commitEdit() yourself to see if the contents are 
valid before using the contents. 


Dates and Numbers 


For starters, let's see how to use the JFormattedTextField to accept input that should be inter- 
nationalized. This includes all forms of dates, times, and numbers—basically, anything whose 
format can be acquired from a DateFormat or NumberFormat object. 

Ifyou provide a Date object or Number subclass to the JFormattedTextField constructor, the 
component passes the input String to the constructor ofthat object type to do the input validation. 
Instead, you should work with the InternationalFormatter class in the java.swing.text 
package by passing a DateFormat or NumberFormat into the constructor. This allows you to 
specify long versus short form for dates and times, as well as currency, percentage, floats, 
and integers for numbers. 


Date and Time Formats 


To demonstrate date and time formatting, the example in Listing 16-7 accepts various date and 
time input. From top to bottom, the inputs are short date format for default locale, full date 
format for United States English, medium date format for Italian, day of week in French, and 
short time format for the default locale. 
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Listing 16-7. Formatted Date and Time Input 


import javax.swing.*; 
import javax.swing.text.*; 
import javax.swing.event.*; 
import java.awt.*; 

import java.text.*; 

import java.util.*; 


public class DateInputSample f 
public static void main(String args[]) ( 
Runnable runner = new Runnable() £ 
public void run() f 
JFrame frame = new JFrame("Date/Time Input”); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


JLabel label; 
JFormattedTextField input; 
JPanel panel; 


BoxLayout layout = 
new BoxLayout(frame.getContentPane(), BoxLayout.Y_AXIS); 
frame.setLayout (layout); 


Format shortDate = 
DateFormat .getDateInstance(DateFormat. SHORT); 
label = new JLabel("Short date:"); 
input = new JFormattedTextField(shortDate); 
input.setValue(new Date()); 
input.setColumns(20); 
panel = new JPanel(new FlowLayout(FlowLayout.RIGHT)); 
panel.add(label); 
panel.add(input); 
frame.add(panel); 


Format fullUSDate = 

DateFormat .getDateInstance(DateFormat.FULL, Locale.US); 
label = new JLabel("Full US date:"); 
input = new JFormattedTextField(fullUSDate); 
input.setValue(new Date()); 
input.setColumns (20); 
panel = new JPanel(new FlowLayout(FlowLayout.RIGHT)); 
panel.add(label); 
panel.add(input); 
frame.add(panel); 
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Format mediumItalian = 

DateFormat .getDateInstance(DateFormat.MEDIUM, Locale. ITALIAN); 
label = new JLabel("Medium Italian date:"); 
input = new JFormattedTextField(mediumItalian); 
input.setValue(new Date()); 
input .setColumns (20); 
panel = new JPanel(new FlowLayout(FlowLayout.RIGHT)); 
panel.add(label); 
panel .add(input); 
frame.add(panel); 


Format dayOfWeek = new SimpleDateFormat("E", Locale.FRENCH); 
label = new JLabel("French day of week:"); 

input = new JFormattedTextField(dayOfeek); 
input.setValue(new Date()); 

input .setColumns (20); 

panel = new JPanel(new FlowLayout(FlowLayout.RIGHT)); 
panel.add(label); 

panel.add(input); 

frame.add(panel); 


Format shortTime = DateFormat .getTimeInstance(DateFormat . SHORT); 
label = new JLabel("Short time:"); 

input = new JFormattedTextField(shortTime); 

input.setValue(new Date()); 

input .setColumns(20); 

panel = new JPanel(new FlowLayout(FlowLayout.RIGHT)); 
panel.add(label); 

panel.add(input); 

frame.add(panel); 


frame.pack(); 
frame.setVisible(true); 
) 
5 
EventQueue.invokeLater(runner); 
) 
) 


Figure 16-6 shows an example of running the program. To start the program in a different 
locale, you can setthe user.language and user. country settings from the command line with a 
command similar to the following 


java -Duser.language=fr -Duser.country=FR DateInputSample 


However, this will alter the valid input only for those formats without a specific locale set. 
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o 


Short date: [3/21/05 


Full US date: [Monday, March 21, 2005 


Medium Italian date: |21 -genh2006 


French day of week: |lun. 


Short time: [5:48 AM 


Figure 16-6. Formatted JFormattedTextField date and time input 


Number Formats 


Numbers work similarly to dates, just with the java.text.NumberFormat class, instead of the 
DateFormat class. The localization that can be done here is with getCurrencyInstance(), 
getInstance(), getIntegerInstance(), getNumberInstance(), and getPercentInstance(). 

The NumberFormat class will deal with the placement of the necessary commas, periods, 
percent signs, and so on. While inputtingthe numbers, extra characters like commas for thousands 
aren't required. The component will add them after they are input where appropriate, as 
shown in the example in Figure 16-7. Notice the positions of decimal points and commas and 
how they differ from locale to locale. 


lolxl 
UK Currency: E2,424.50 


Generaliinstance: (2,4245 


Italian integer: (2,424 


French Number: [2 424,5 


Raw Number: (2 424.5 


Figure 16-7. Formatted JFormattedTextField numeric input 


Listing 16-8 shows the program that generated Figure 16-7. Each input field starts with a 
value of 2424.50. In the case of the integer version, the input value is rounded. When setting the 
contents of a JFormattedTextField, use the setValue() method, not the setText() method. 
This will ensure that the text contents are validated. 


Listing 16-8. Formatted Numeric Input 


import javax.swing.*; 
import javax.swing.text.*; 
import javax.swing.event.*; 
import java.awt.*; 

import java.text.*; 

import java.util.*; 
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public class NumberInputSample ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("Number Input”); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
Font font = new Font("SansSerif", Font.BOLD, 16); 


JLabel label; 
JFormattedTextField input; 
JPanel panel; 


BoxLayout layout = 
new BoxLayout(frame.getContentPane(), BoxLayout.Y_AXIS); 
frame.setLayout (layout); 


Format currency = 
NumberFormat .getCurrencyInstance(Locale.UK); 
label = new JLabel("UK Currency:"); 
input = new JFormattedTextField(currency); 
input.setValue(2424.50); 
input .setColumns (20); 
input .setFont (font); 
panel = new JPanel(new FlowLayout(FlowLayout.RIGHT)); 
panel.add(label); 
panel.add(input); 
frame.add(panel); 


Format general = NumberFormat.getInstance(); 

label = new JLabel("General/Instance:"); 

input = new JFormattedTextField(general); 
input.setValue(2424.50); 

input .setColumns (20); 

input.setFont (font); 

panel = new JPanel(new FlowLayout(FlowLayout.RIGHT)); 
panel.add(label); 

panel .add(input); 

frame.add(panel); 


Format integer = NumberFormat.getIntegerInstance(Locale.ITALIAN); 
label = new JLabel("Italian integer:"); 

input = new JFormattedTextField(integer); 
input.setValue(2424.50); 

input.setColumns (20); 

input.setFont (font); 
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panel = new JPanel(new FlowLayout(FlowLayout.RIGHT)); 
panel.add(label); 
panel.add(input); 
frame.add(panel); 


Format number = NumberFormat.getNumberInstance(Locale.FRENCH); 
label = new JLabel("French Number:"); 

input = new JFormattedTextField(number); 
input.setValue(2424.50); 

input.setColumns(20); 

input.setFont (font); 

panel = new JPanel(new FlowLayout(FlowLayout.RIGHT)); 
panel.add(label); 

panel.add(input); 

frame.add(panel); 


label = new JLabel("Raw Number:"); 
input = new JFormattedTextField(2424.50); 
input.setColumns (20); 
input.setFont (font); 
panel = new JPanel(new FlowLayout(FlowLayout.RIGHT)); 
panel.add(label); 
panel.add(input); 
frame.add(panel); 
frame.pack(); 
frame.setVisible(true); 
) 
5 
EventQueue.invokelLater(runner); 
) 
y 


The last of the five JFormattedTextField examples in Figure 16-7 initializes the component 
with a double. The value 2424.50 is auto-boxed into a Double object. There's nothing wrong 
with passing an object to the constructor. However, you might notice some irregularities while 
entering values into the field. A value seems to always start with one decimal point, even though 
more input digits are accepted. Instead of using a Format object to go from text to Object and 
back, the Double constructor that accepts a String is used. 

When you pass in a java.text.Format object to the JFormattedTextField constructor, this 
internally is mapped to either a DateFormatter or NumberFormatter object. Both of these are 
subclasses of the InternationalFormatter class. The inner class named JFormattedTextField. 
AbstractFormatterFactory manages the use of the formatter objects within JFormattedTextField. 
The factory will insta11() the formatter as the user enters the JFormattedTextField and 
uninstall() iton departure, ensuring the formatter is active in only one text field at a time. 
These instal11() and uninstal1() methods are inherited by the formatter classes from the 
JFormattedTextField.AbstractFormatter superclass of all formatters. 
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Input Masks 


Beyond numbers and dates, the JFormattedTextField supports user input following a pattern 
mask. For instance, if an input field is a United States social security number (SSN), it has a 
typical pattern of number, number, number, dash, number, number, dash, number, number, 
number, number. With the help ofthe MaskFormatter class, you can specify the mask using the 


or 


characters listed in Table 16-9. 


Table 16-9. Special Characters for Masks 


Character Description 

$ Matches numeric character (Character.isDigit()) 

H Matches hexadecimal number (0-9, af, and A—F) 

A Matches alphanumeric character (Character.is Letter0rDigit()) 

? Matches alphabetic character (Character.isLetter()) 

U Matches uppercase letter; maps lowercase to uppercase 

L Matches lowercase letter; maps uppercase to lowercase 

* Wildcard, matches any character 

: Escape character to have literal strings/separators in input field 
For example, this formatter creates an SSN mask: 

new MaskFormatter ("tHe +! 4H") 


The apostrophes in the mask mean the character after each is treated literally—in this 
case, as a dash. You have the option of passing this formatter to the JFormattedTextField 


constructor or configuring the text field with the setMask() method. 


ac 


To demonstrate, Listing 16-9 includes two JFormattedTextField components: one to 


cept SSNs and the other United States phone numbers. 


Listing 16-9. Formatted Masked Input 


im 
im 
im 
im 


port javax.swing.*; 

port javax.swing.text.*; 
port javax.swing.event.*; 
port java.awt.*; 

port java.text.*; 


import java.util.*; 


blic class MaskInputSample £ 
public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("Mask Input"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
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JLabel label; 
JFormattedTextField input; 
JPanel panel; 
MaskFormatter formatter; 


BoxLayout layout = 
new BoxLayout(frame.getContentPane(), BoxLayout.Y_AXIS); 
frame.setLayout (layout); 


try ( 
label = new JLabel("SSN"); 
formatter = new MaskFormatter("HHH'-4H' HH"); 
input = new JFormattedTextField(formatter); 
input.setValue("123-45-6789"); 
input .setColumns(20); 
panel = new JPanel(new FlowLayout(FlowLayout.RIGHT)); 
panel .add(label); 
panel .add(input); 
frame.add(panel); 

j catch (ParseException e) f 
System.err.printin("Unable to add SSN"); 


try ( 
label = new JLabel1("US Phone"); 
formatter = new MaskFormatter("' (HH) HR AA); 
input = new JFormattedTextField(formatter); 
input .setColumns (20); 
panel = new JPanel(new FlowLayout(FlowLayout.RIGHT)); 
panel .add(label); 
panel .add(input); 
frame.add(panel); 

$ catch (ParseException e) f 
System.err.println("Unable to add Phone”); 


J 


frame.pack(); 
frame.setVisible(true); 
J 
5 
EventQueue.invokeLater(runner); 
) 
J 


Figure 16-8 shows the output of the program. In this example, the SSN field starts with an 
initial value, while the phone number field does not. 
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SSN (1 23-45-6789 


US Phone [() - 


Figure 16-8. Formatted masked input in JFormattedTextFields 


The MaskFormatter does provide some customization options. By default, the formatter is 
in overwrite mode, so as you type, the entered digits will replace each number and space in the 
input field. Set the overwriteMode property to false to disable this. Typically, this isn't necessary, 
though for entering in long dates, it can be helpful. 

If you wish to have a different character as the placeholder character, before a position is 
filled in the mask, setthe placeholderCharacter property of the MaskFormatter. To demonstrate, 
add the following line to the phone number formatter in Listing 16-9: 


formatter.setPlaceholder('*'); 


You'll see the results in the bottom text field shown in Figure 16-9. 


SSN [123-45-6789 


US Phone |(++) +=-=== 


Figure 16-9. Formatted masked input with a placeholder 


Another useful MaskFormatter property is validCharacters, for restricting which alpha- 
numeric characters are valid for an input field. 


DefaultFormatterFactory Class 


The DefaultFormatterFactory class found in the javax.swing.text package offers a way to 
have different formatters for displaying values, editing values, and a special case ofa null 
value. It offers five constructors, starting with no parameters and then adding an additional 
AbstractFormatter parameter for each constructor. 


public DefaultFormatterFactory() 
DefaultFormatterFactory factory = new DefaultFormatterFactory() 


public DefaultFormatterFactory(JFormattedTextField.AbstractFormatter defaultFormat) 
DateFormat defaultFormat = new SimpleDateFormat("yyyy--MMMM-- dd"); 

DateFormatter defaultFormatter = new DateFormatter(displayFormat); 
DefaultFormatterFactory factory = new DefaultFormatterFactory(defaultFormatter); 


public DefaultFormatterFactory(JFormattedTextField.AbstractFormatter defaultFormat, 
JFormattedTextField.AbstractFormatter displayFormat) 

DateFormat displayFormat = new SimpleDateFormat ("yyyy--MMMM- -dd">); 

DateFormatter displayFormatter = new DateFormatter(displayFormat); 

DefaultFormatterFactory factory = new DefaultFormatterFactory(displayFormatter, 
displayFormatter); 


CHAPTER 16 ADVANCED TEXT CAPABILITIES 


public DefaultFormatterFactory(JFormattedTextField.AbstractFormatter defaultFormat, 
JFormattedTextField.AbstractFormatter displayFormat, 
JFormattedTextField.AbstractFormatter editFormat) 

DateFormat displayFormat = new SimpleDateFormat ("yyyy--MMMM--dd"); 

DateFormatter displayFormatter = new DateFormatter(displayFormat); 

DateFormat editFormat = new SimpleDateFormat ("MM/dd/yy"); 

DateFormatter editFormatter = new DateFormatter(editFormat); 

DefaultFormatterFactory factory = new DefaultFormatterFactory( 
displayFormatter, displayFormatter, editFormatter); 


public DefaultFormatterFactory(JFormattedTextField.AbstractFormatter defaultFormat, 
JFormattedTextField.AbstractFormatter displayFormat, 
JFormattedTextField.AbstractFormatter editFormat, 
JFormattedTextField.AbstractFormatter nullFormat) 
DateFormat displayFormat = new SimpleDateFormat ("yyyy--MMMM--dd"); 
DateFormatter displayFormatter = new DateFormatter(displayFormat); 
DateFormat editFormat = new SimpleDateFormat ("MM/dd/yy"); 
DateFormatter editFormatter = new DateFormatter(editFormat); 
DateFormat nullFormat = new SimpleDateFormat("'nul1'"); 
DateFormatter nullFormatter = new DateFormatter(nullFormat); 
DefaultFormatterFactory factory = new DefaultFormatterFactory( 
displayFormatter, displayFormatter, editFormatter, nullFormatter); 


There isn't much magic in the use ofDefaultFormatterFactory. Just create one and pass it 
along to the JFormattedTextField constructor. Then the state of the text field will determine 
which formatter is used to show the current value. Typically, the display formatter is repeated 
for the default settings. If any of the formatters is null or unset, the default formatter will be 
used instead. 


Summary 


In this chapter, you saw several of the more advanced aspects of working with the JEC/Project 
Swing text components. You looked into how to use the predefined TextAction objects to create 
working user interfaces without defining any of your own event-handling capabilities. In addition, 
you explored the JTextPane and how to create multiple-attributed text within a JTextPane 
through the AttributeSet, MutableAttributeSet, SimpleAttributeSet, and StyleConstants. 
You also saw how to create tab stops within a Document and glanced at the EditorKit facilities 
of Swing, exploring the details of the HTMLEditorKit specifically. Finally, you learned more 
about accepting formatted input with the JFormattedTextField. 

For additional information about the Swing text package, be sure to stop by The Swing 
Connection at http: //java.sun.com/products/jfc/tsc/articles/text/overview/. 

In Chapter 17, you'll explore the Swing component for displaying hierarchical data: 
the JTree. 
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Trees 


l. Chapter 16, you looked at how to work with the text document capabilities within the Swing 
component set. In this chapter, you'll learn how to work with Swing/'s tree class, the JTree 
component. 


Introducing Trees 


The JTree component is the visual component for displaying hierarchical data elements, also 
known as nodes. Using this tree metaphor, imagine the tree is flipped upside down. The node 
at the top of the tree is called the root. Extending from the root node of the tree are branches to 
other nodes. If a node does not have any branches coming out ofit, that node is called a leaf 
node. See Figure 17-1 for a simple JTree. 


Joa 

JTree = 
o- colors 
9 UU sports E. 
Ey basketball 
Ey soccer 
Ey football 


Figure 17-1. Sample JTree 


Many interconnected classes are used in the composition of the JTree. First, the JTree 
implements the Scrollable interface, so that you can place the tree within a JScrol11Pane for scroll 
management. The display of each node within the tree is controlled by implementations of the 
TreeCellRenderer interface; by default, the implementation is the DefaultTreeCellRenderer 
class. Nodes of a tree are editable with implementations of TreeCel1Editor. Two editor implemen- 
tations are available: one offering a text field with DefaultTreeCel1Editor and one offering a check 
box or combo box with DefaultCellEditor, which extends from the generic AbstractCellEditor. 
If these classes don't provide what you need, you can place custom editors within an 
EditorContainer. 
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Note The DefaultCellEditor class can also be used as a cell editor with the JTable component. 
The JTable component is described in Chapter 18. 


By default, the actual nodes of the JTree are implementations ofthe TreeNode interface or 
its subinterface MutableTreeNode. The DefaultMutableTreeNode class is one such implementa- 
tion that's commonly used, with the JTree.DynamicUtilTreeNode inner class helping to create 
the tree nodes. The many tree nodes make up the TreeModel for the JTree, stored by default 
into an instance of the DefaultTreeModel class. 

Tree selection is managed by a TreeSelectionModel implementation, with a defaultimple- 
mentation ofDefaultTreeSelectionModel available. The JTree.EmptySelectionModel is also 
available if you do not want the nodes of the tree to be selectable. The path of nodes from the 
root of the tree to the selected node is maintained within a TreePath, with the help ofa RowMapper 
implementation to map rows to paths. 


Note The tree-specific classes are found in the javax.swing.tree package. The event-related classes 
are in the javax.swing.event package. 


JTree Glass 


The JTree class forms the basis for visually displaying a set of hierarchical data elements. 


Creating a JTree 


There are seven different ways to create a JTree, with five different ways to specify the nodes: 


public JTree() 
JTree tree = new JTree(); 


public JTree(Hashtable value) 
JTree tree = new JTree(System.getProperties()); 


public JTree(Object value[]) 
public static void main (String args[]) ( 
JTree tree = new JTree(args); 


q 


public JTree(Vector value) 
Vector vector = new Vector(); 
vector.add("One”); 
vector.add("Two"); 

JTree tree = new JTree(vector); 


CHAPTER 17 TREES 


public JTree(TreeModel value) 
JTree tree = new JTree(aTreeModel); 


public JTree(TreeNode value) 
JTree tree = new JTree(aTreeNode); 


public JTree(TreeNode value, boolean asksAllowsChildren) 
JTree tree = new JTree(aTreeNode, true); 


The first ofthe constructors is the no-argument variety. Surprisingly, it has a default data 
model with some nodes in it (see Figure 17-1). Normally, you would change the data model of 
the default tree after creation with setModel(TreeModel newModel). 

The next three constructors seem to belong together. Creation of a JTree from a Hashtable 
made up of key/value pairs uses the set of keys for the nodes and values for the children, whereas 
creation from an array or Vector uses the elements as the nodes. This may seem to imply that 
the tree is only one level deep, but actually the tree can be infinitely deep ifthe key or element 
itselfis in a Hashtable, an array, or a Vector. 

The remaining three constructors use the custom data structures of JTree, which will be 
explained later in this chapter. By default, only those nodes that have children are leaf nodes. 
However, trees can be constructed with partial nodes that won't get children until later. The 
last of these three constructors causes a method to be called when you try to open a parent 
node, instead of the parent node just looking for child nodes. 


Tip If the value for a key in a Hashtable is another Hashtable, array, or Vector, you can create a multi- 
level tree by using the top-level Hashtable as the constructor argument. 


AsI mentioned, using a Hashtable, an array, or a Vector as the argument in the constructor 
tree does, in fact, allow you to create multilevel trees. There are two minor problems with this, 
however: the root node isn't visible, and it automatically has a data element of root. The text 
label for any other nodes of type Hashtable, array, or Vector is the result of toString(). The 
default text is not desirable in any of these three instances. You get either the results of the 
toString() method ofthe Object class for an array or a label that includes a list of all the elements 
in the Hashtable or Vector. In the case of an Object array, the output would look something like 
[Ljava.lang.Object;0fa8d8993. This is certainly not something you want to show a user. 

Although you cannot override toString() (because there is no array class to subclass), you 
can subclass Hashtable or Vector to provide a different toString() behavior. Offering a name 
to the constructor of this new class allows you to provide a text label to use in the tree when the 
Hashtable or Vector is not the root node. The class shown in Listing 17-1 defines this behavior 
for a Vector subclass. In addition to the constructor providing a name, the class also adds a 
constructor that initializes the Vector to the contents of an array. 
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Listing 17-1. Named Vector 


import java.util.Vector; 
public class NamedVector<E> extends Vector<E> ( 
String name; 
NamedVector(String name) £ 
this.name = name; 


) 


NamedVector(String name, E elements[]) ( 
this.name = name; 
for (int i=0, n=elements.length; i<n; i++) ( 
add(elements[i]); 


J 


J 
public String toString() ( 


return "[" + name + "]"; 


J 
y 


Figure 17-2 shows an example of the NamedVector class in action. 


lol 
(E [One] 

7 3 [Two] 

Cy Mercury 

Py venus 

Cy Mars 

e | 
2 UU fjava.runtime.name=Java(TM) 2 Runtime E 

Ey java.runtime.name 

Ey sun.bootlibrary. path 

Ey java. vm version 

Ey javawm.vendor 

Ey javawendor.url 

Ey path.separator 

Py jarawvm.name 


Figure 17-2. Sample JTree with the Vector subclass node 
Listing 17-2 shows the source used to generate the example in Figure 17-2. 


Listing 17-2. Named Vector Usage 


import javax.swing.*; 
import javax.swing.tree.*; 
import java.awt.*; 

import java.util.*; 


public class TreeArraySample ( 
public static void main(final String args[]) ( 
Runnable runner = new Runnable() f 
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public void run() £ 
JFrame frame = new JFrame("JTreeSample"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


Vector<String> oneVector = new NamedVector<String>("One", args); 
Vector<String> twoVector = new NamedVector<String>("Two", 
new String[]("Mercury", "Venus", "Mars")); 
Vector<0bject> threeVector = new NamedVector<Object>("Three"); 
threeVector.add(System.getProperties()); 
threeVector.add(twoVector); 
Object rootNodes[] = [oneVector, twoVector, threeVector); 
Vector<0bject> rootVector = new NamedVector<0bject>("Root", rootNodes); 
JTree tree = new JTree(rootVector); 
frame.add(tree, BorderLayout.CENTER); 
frame.setSize(300, 300); 
frame.setVisible(true); 
) 
5 
EventQueue.invokelLater(runner); 
y 
) 


Scrolling Trees 


If you created and ran the program in Listing 17-2, you would notice one small problem. When 
all the parent nodes are open, the tree is too bigfor the initial screen size. Not only that, but you 
also can't see the nodes at the bottom of the tree. To fix this situation, it's necessary to place 
instances of the JTree class within a JScrol1Pane so that the scroll pane can manage the scrolling 
aspects of the tree. Similar to the JTextArea class described in Chapter 15, the JTree class 
implements the Scrollable interface for scrolling support. 

Replacing the two boldfaced lines in the example in Listing 17-2 with the following three 
lines will place the tree within a scroll pane. This will cause the tree to appear in a scrollable 
region when the tree is too large for the available display space. 


// Change from 

JTree tree = new JTree(rootVector); 
frame.add(tree, BorderLayout.CENTER); 

// To 

JTree tree = new JTree(rootVector); 

JscrollPane scrollPane = new JScrollPane(tree); 
frame.add(scrollPane, BorderLayout.CENTER); 


In addition to using a JScro11Pane for scrolling, you can manually scroll the visible content 
in the scrolling region. Use the public void scrollPathToVisible(TreePath path) and public 
void scrollRowToVisible(int row) methods to move a particular tree path or row into some 
part of the visible area. The row of a node indicates the number of nodes above the current 
node to the top of the tree. This differs from the level of the tree, which is the number of ancestors 
(or parent nodes) a node has. Figure 17-3 should help you visualize this difference. In the 
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window on the left, the soccer node is at level 2 and row 8. When the colors node is closed, as 
in the window on the right, the soccer node remains on level 2 but moves to row 4, because the 
blue, violet, red, and yellow rows are no longer visible. 


lol xl J0lx] 
1 JTree ¡al a JTree OS 
9 U colors o- 1 colors 

Ey blue hÓs 

FP violet |) basketball 

Py rea Level 2/Row 4 ——> E soccer 

O) yellow Y football 
?¿Hsp EY hockey 

[y basketball 9 (food 

E soccer] Level 2/Row 8 [y hot dogs 

IN football D pizza 
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E hot dogs | 

Dj pizza 5] 


Figure 17-3. Rows versus levels of a tree 


JTree Properties 


Table 17-1 lists the 40 specific properties of JTree. You will explore many ofthese as you look at 
the different classes that make up JTree. 


Table 17-1. Tree Properties 


Property Name Data Type Access 
accessibleContext  AccessibleContext  Read-omly 
anchorSelectionPath TreePath Read-write bound 
cellEditor TreeCellEditor Read-write bound 
cellRenderer TreeCellRenderer Read-write bound 
dragEnabled boolean Read-write 
editable boolean Read-write bound 
editing boolean Read-only 
editingPath TreePath Read-only 
expandsSelectedPath boolean Read-write bound 
fixedRowHeight boolean Read-only 
invokesStopCellEditing boolean Read-write bound 
largeModel boolean Read-write bound 
lastSelectedPathComponent Object Read-only 


leadSelectionPath TreePath Read-write bound 


Table 17-1. JTree Properties (Continued) 
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Property Name Data Type Access 
leadSelectionRow int Read-only 
maxSelectionRow int Read-only 
minSelectionRow int Read-only 

model TreeModel Read-write bound 
preferredScrollableViemportSize Dimension Read-only 
rootVisible boolean Read-write bound 
rowCount int Read-only 
rowHeight int Read-write bound 
scrollableTracksViemportHeight boolean Read-only 
scrollableTracksViemportWidth boolean Read-only 
scroll1sOnExpand boolean Read-write bound 
selectionCount int Read-only 
selectionEmpty boolean Read-only 
selectionModel TreeSelectionModel Read-write bound 
selectionPath TreePath Read-write 
selectionPaths TreePath[ ] Read-write 
selectionRow int Write-only 
selectionRows int[ ] Read-write 
showsRootHandles boolean Read-write bound 
toggleClickCount int Read-write bound 
treeExpansionListeners TreeExpansionListener[ ] Read-only 
treeSelectionListeners TreeSelectionListener[ ] Read-only 
treeWillExpandListeners TreeWillExpandListener[ ] Read-only 

UI TreeUul Read-write 
UIClassID String Read-only 
visibleRowCount int Read-write bound 


Some JTree properties are closely interrelated. For instance, when the rowHeight property 
is positive, it means that the node at each rowis displayed with a fixed height, no matter what size 
the nodes within the tree should be. When the rowHeight property is negative, the cellRenderer 
property determines the rowHeight. So, the value of ronHeight determines the setting of the 
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fixedRowHeight property. Changing the value of rowHeight to a value such as 12 pixels results in 
the fixedRowHeight property having a setting of true. 

The largeModel property setting is a suggestion to the TreeUl to help it display the tree. 
Initially, this setting is false because a tree has many data elements and you don't want the 
user interface component to cache excessive information (such as node renderer sizes) about 
the tree. For smaller models, caching information about a tree doesn't require as much memory. 

The current setting of lastSelectedPathComponent property is the contents of the last selected 
node. At any time, you can ask a tree what is selected. If nothing is selected, this property's 
value will be null. Because trees support multiple selections, the lastSelectedPathComponent 
property doesn't necessarily return all selected nodes. You can also modify the selection path 
with the anchorSelectionPath and leadSelectionPath properties. 

The three selection row properties—leadSelectionRow, minSelectionRow, and 
maxSelectionRow—are interesting in that the row values can change based on another parent 
node's opening or closing. When a single node in the tree is selected, all three properties have 
the same setting. You can get an array of all selected rowindices with the selectionRows property. 
However, there is no way to map a row number to a node in the tree. Instead, use the 
selectionPaths property, which provides an array of TreePath elements. As you'll soon see, 
each TreePath includes the selected node and all nodes on the path from the root node to the 
selected node. 

There are three visibility-related settings of a tree. You can adjust the preferred number of 
rows to display for the tree by setting the visibleRowCount property. By default, the setting is 20. 
This setting is valid only when a particular tree is within a JScrol1Pane or some other component 
that uses the Scrollable interface. The second visibility-related setting has to do with whether 
the root nodeis visible. When the tree is created from a Hashtable, array, or Vector constructor, the 
root isn't visible. Otherwise, it will be visible initially. Changing the rootVisible property allows 
you to alter this setting. The other visibility-related setting has to do with the icon next to the root 
node. By default, there is no icon at the root level to show the open or closed state ofthe root of 
the tree. All nonroot nodes always have this type oficon. To show the root icon, set the 
showsRootHandles property to true. 

Three additional selection-oriented properties are also available. The toggleClickCount 
property allows you to control how many clicks over a parent node will trigger selection or 
expansion ofthe node. The default settingis 2. The scrol1sOnExpand property causes the tree to 
scroll when a node is expanded such that as many descendants as possible will be visible. By 
default, this is true. The third property, expandsSelectedPath, is true by default, causing the 
selected path for a node to be expanded when programmatically selected. If, however, you 
don't wish to expand the tree upon programmatic selection, you can set this to false and leave 
the path hidden. 


Customizing a JTree Look and Feel 


Each installable Swing look and feel provides a different JTree appearance and set of default 
UTResource values. Figure 17-4 shows the appearance of the JTree container for the preinstalled 
set of look and feel types: Motif, Windows, and Ocean. 
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Figure 17-4. JTree under different look and feel types 


The available set ofUIResource-related properties for a JTree is shown in Table 17-2. For 


the JTree component, there are 43 different properties. 


Table 17-2. JTree UlResource Elements 


Property String 


Tree 


Tree. 
Tree. 
Tree. 
Tree. 
Tree. 
Tree. 
Tree. 
Tree. 
Tree. 
Tree. 
Tree. 


Tree. 


Tree 


.actionMap 

ancestorInputMap 
background 
changeSelectionWithFocus 
closedIcon 

collapsedIcon 
drawDashedFocusIndicator 
drawHorizontalLines 
drawsFocusBorderAroundIcon 
drawVerticalLines 
editorBorder 
editorBordersSelectionColor 
expandedIcon 


.expanderSize 


Object Type 
ActionMap 
InputMap 
Color 
Boolean 
Icon 

Icon 
Boolean 
Boolean 
Boolean 
Boolean 
Border 
Color 
Icon 


Integer 
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Table 17-2. JTree UlResource Elements (Continued) 


Property String 


Tree 


Tree 


Tree 


Tree 


Tree. 
Tree. 
Tree. 


Tree. 


Tree. 
Tree. 
Tree. 


Tree. 


Tree. 
Tree. 
Tree. 


Tree. 


Tree. 
Tree. 


Tree. 


Tree. 
Tree. 
Tree. 
Tree. 
Tree. 
Tree. 
Tree. 
Tree. 


Tree. 


focusInputMap 
focusInputMap.RightToLeft 
font 


foreground 


«hash 


iconBackground 
iconForeground 
iconHighlight 


iconShadow 


.leafIcon 


leftChildIndent 
line 
lineTypeDashed 


openlcon 


.padding 


paintLines 
rendererUseTreeColors 


rightChildIndent 


.TowHeight 


scrollsHorizontallyAndVertically 
scrol1sOnExpand 
selectionBackground 
selectionBorderColor 
selectionForeground 
showsRootHandles 

textBackground 

textForeground 


timeFactor 


TreeUul 


Object Type 
InputMap 
InputMap 
Font 
Color 
Color 
Color 
Color 
Color 
Color 
Icon 
Integer 
Color 
Boolean 
Icon 
Integer 
Boolean 
Boolean 
Integer 
Integer 
Boolean 
Boolean 
Color 
Color 
Color 
Boolean 
Color 
Color 
Integer 
String 
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Of the many different JTree resources, five are for the various icons displayed within the 
JTree. To see howthe five icons are positioned, examine Figure 17-5. Ifyou just want to change 
the icons (and possibly the colors) of a tree, all you need to do is change the icon properties 
with lines such as the following: 


UlManager.put("Tree.openIcon", new DiamondIcon(Color.RED, false)); 


Open 


+£ Icon Identification 


Collapsed — $ 
Expanded —————>>y 


Leaf UL > «etba 


Figure 17-5. JTree icons 


colors 


Closed 


The purpose of the Tree.hash color property may not be immediately obvious. This color 
is for the lines drawn to connect nodes. With the Metal look and feel, and Ocean theme, by 
default, angled lines connect the nodes. To enable the drawing of these lines, you must set the 
JTree.lineStyle client property. This property isn't a UTResource property, but rather a client 
property set with the public final void putClientProperty(Object key, Object value) method 
of JComponent. The JTree.lineStyle property has the following valid settings: 


+ None, for not drawing lines to connect nodes 


+ Angled, the default setting for Ocean, for drawing lines in the Tree.hash color to connect 
the nodes 


+ Horizontal, for drawing horizontal lines between first-level nodes in the Tree. line color 


Note The JTree.]lineStyle client property is used only by the Metal look and feel. Ifthe current look and 
feel isn't Metal or one of ¡ts themes like Ocean, the property setting will be ignored if set (unless a custom look 
and feel takes advantage of the setting). The other system-provided look and feel classes don't use this setting. 


With client properties, you first must create the tree and then set the property. This client 
property is specific to tree components, and it is not set for all trees. Therefore, creating a tree 
with no lines entails using the following lines of code: 


JTree tree = new JTree(); 
tree.putClientProperty("JTree.lineStyle", "None"); 


Figure 17-6 shows the results. 
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Figure 17-6. A Tree with no connection lines 


The following lines produce horizontal lines between level-one nodes: 


UlManager.put("Tree.line", Color.GREEN); 
JTree tree = new JTree(); 
tree.putClientProperty("JTree.linestyle", "Horizontal"); 


Figure 17-7 shows how the horizontal lines appear. 
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Figure 17-7. A JTree with horizontal level lines 


TreeCellRenderer Interface 


Each of the nodes within the JTree has an installed cell renderer. It's the responsibility of the 
renderer to draw the node and clearly display its state. The default renderer is basically a 
JLabel, which allows you to have both text and an icon within the node. However, any compo- 
nent can serve as the node renderer. The default renderer displays an icon that represents the 
state of the node. 


Note The tree cell renderer is just that—a renderer. If the renderer were, say, a JButton, it wouldn't be 
selectable but would nevertheless be drawn to look just like a JButton. 


The configuration of each node rendereris defined by the TreeCel1Renderer interface. Any 
class implementing this interface can serve as a renderer for your JTree. 


public interface TreeCellRenderer ( 
public Component getTreeCellRendererComponent(JTree tree, Object value, 
boolean selected, boolean expanded, boolean leaf, int row, boolean hasFocus); 
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When it's time to draw a tree node, that tree asks its registered TreeCellRenderer howto 
display that specific node. The node itselfis passed in as the value argument so that the renderer 
has access to its current state to determine how to render this state. To change the installed 
renderer, use public void setCellRenderer(TreeCellRenderer renderer). 


DefaultTreeCellRenderer Class 


The DefaultTreeCellRenderer class serves as the default tree cell renderer. This classis a JLabel 
subclass, so it can support capabilities such as displaying tooltip text or pop-up menus specific 
to a node. It has only a no-argument constructor. 

When used by a JTree, the DefaultTreeCellRenderer uses the various default icons (as 
shown earlier in Figure 17-5) to display the current state of the node and a text representation 
of the data for the node. The text representation is acquired by calling the toString() method 
for each node of the tree. 


DefaultTreeCellRenderer Properties 


Table 17-3 shows the 14 properties added (or altered) with DefaultTreeCellRenderer. Because 
the default renderer happens to be a JLabel, you also acquire many additional properties from it. 


Table 17-3. DefaultTreeCellRenderer Properties 


Property Name Data Type Access 

background Color Write-only 
backgroundNonSelectionColor Color Read-write 
backgroundSelectionColor Color Read-write 
borderSelectionColor Color Read-write 
closedIcon Icon Read-write 
defaultClosedIcon Icon Read-only 
defaultLeafIcon Icon Read-only 
defaultOpenIcon Icon Read-only 
font Font Read-write 
leafIcon Icon Read-write 
openIcon Icon Read-write 
preferredSize Dimension Read-only 
textNonSelectionColor Color Read-write 


textSelectionColor Color Read-write 
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Ifyou don't like working with the UlManager or just wantto change the icons, font, or colors 
for a single tree, you don't need to create a custom tree cell renderer. Instead, you can ask the 
tree for its renderer and customize it to display the icons, font, or colors you want. Figure 17-8 
shows a JTree with an altered renderer. Instead of creating a new renderer, the existing default 
renderer was customized with the following source: 


JTree tree = new JTree(); 

DefaultTreeCellRenderer renderer = (DefaultTreeCellRenderer)tree.getCellRenderer(); 
// Swap background colors 

Color backgroundSelection = renderer.getBackgroundSelectionColor(); 
renderer.setBackgroundSelectionColor(renderer.getBackgroundNonSelectionColor()); 
renderer.setBackgroundNonSelectionColor(backgroundSelection); 

// Swap text colors 

Color textSelection = renderer.getTextSelectionColor(); 
renderer.setTextSelectionColor(renderer.getTextNonSelectionColor()); 
renderer.setTextNonselectionColor(textSelection); 
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Figure 17-8. A JTree with an altered default renderer 


Remember that TreeUl caches renderer size information. Ifa change to the renderer 
changes the renderer size, this cache isn't updated. To get around the problem, it's necessary 
to signal to the tree that the cache is invalid. One such signal is to change the rowHeight prop- 
erty. As long as the current rowHeight property setting isn't positive, the TreeUI must ask the 
renderer for its height. Therefore, decreasing the value by 1 has a side effect ofinvalidating the 
cached renderer size information, causing the tree to be displayed with the proper initial sizes 
for all the renderers. Adding the following source to the previous example demonstrates this. 


renderer.setFont(new Font("Dialog", Font.BOLD | Font.ITALIC, 32)); 
int rowHeight = tree.getRowHeight(); 
if (rowHeight <= 0) £ 
tree.setRowHeight (rowHeight - 1); 
y 


The window on the left in Figure 17-9 shows the effect this addition has on Figure 17-8. 
If you didn't change the rowHeight property to invalidate the display cache, you would get the 
effect shown in the right window instead. 
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Figure 17-9. You must properly modify the size of a tree renderer. 


Creating a Custom Renderer 


If the nodes of your JTree consist of information that is too complex to display within the text 
of a single JLabel, you can create your own renderer. As an example, consider a tree in which 

the nodes describe books by their title, author, and price, as shown in Figure 17-10. In this case, 
the renderer can be a container in which a separate component displays each part. 
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Figure 17-10. A JTree with a custom renderer 


To describe each book in this example, you need to define a class for storingthe necessary 
information, as shown in Listing 17-3. 


Listing 17-3. Book Class Definition 


public class Book f 

String title; 

String authors; 

float price; 

public Book(String title, String authors, float price) ( 
this.title = title; 
this.authors = authors; 
this.price = price; 


J 
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public String getTitle() ( 
return title; 
) 
public String getAuthors() ( 
return authors; 
) 
public float getPrice() ( 
return price; 
) 
) 


To render a book as a node in the tree, you need to create a TreeCellRenderer implementation. 
Because the books are leaf nodes, the custom renderer will use a DefaultTreeCellRenderer to 
render all the other nodes. The key part ofthe rendereristhe getTreeCellRendererComponent(). 
In the event that the node data received by this method is of type Book, it stores the appropriate 
information in the different labels and returns a JPanel as the renderer, with labels for each of 
the book titles, authors, and prices. Otherwise, the getTreeCell1RendererComponent() method 
returns the default renderer. 

Listing 17-4 contains the source for this custom renderer. Notice that it uses the same 
selection colors as the remaining nodes of the tree so that the book nodes don't appear out 
of place. 


Listing 17-4. Book Cell Renderer 


import javax.swing.*; 
import javax.swing.tree.*; 
import java.awt.*; 


public class BookCellRenderer implements TreeCellRenderer ( 

JLabel titleLabel; 

JLabel authorsLabel; 

JLabel priceLabel; 

JPanel renderer; 

DefaultTreeCellRenderer defaultRenderer = new DefaultTreeCellRenderer(); 

Color backgroundSelectionColor; 

Color backgroundNonSelectionColor; 

public BookCellRenderer() ( 
renderer = new JPanel(new GridLayout(0, 1)); 
titlelabel = new JLabel(" "); 
titleLabel.setForeground(Color.BLUE); 
renderer.add(titlelabel); 
authorslabel = new JLabel(" "); 
authorsLabel.setForeground(Color.BLUE); 
renderer.add(authorsLabel); 
pricelabel = new Jlabel(" "); 
pricelabel.setHorizontalAlignment (JLabel.RIGHT); 
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pricelabel.setForeground(Color.RED); 
renderer.add(priceLabel); 
renderer.setBorder(BorderFactory.createlineBorder(Color.BLACK)); 
backgroundSelectionColor = defaultRenderer.getBackgroundSelectionColor(); 
backgroundNonSelectionColor = defaultRenderer.getBackgroundNonSelectionColor(); 
) 
public Component getTreeCellRendererComponent(JTree tree, Object value, 
boolean selected, boolean expanded, boolean leaf, int row, boolean hasFocus) 4 
Component returnValue = null; 
if ((value != null) 88 (value instanceof DefaultMutableTreeNode)) f 
Object user0bject = ((DefaultMutableTreeNode)value).getUser0bject(); 
if (user0bject instanceof Book) ( 
Book book = (Book)user0bject; 
titlelabel.setText(book.getTitle()); 
authorsLabel.setText(book.getAuthors()); 
pricelabel.setText("" + book.getPrice()); 
if (selected) ( 
renderer.setBackground(backgroundSelectionColor); 
) else f 
renderer.setBackground(backgroundNonSelectionColor); 
li 
renderer.setEnabled(tree.isEnabled()); 
returnValue = renderer; 
J 
y 
if (returnValue == null) ( 
returnValue = defaultRenderer.getTreeCellRendererComponent(tree, value, 
selected, expanded, leaf, row, hasFocus); 
h 
return returnValue; 
) 
J 


Tip The JLabel components are created with an initial text label consisting of a space. Having a nonempty 
label gives each component some dimensions. The TreeUI caches node sizes to improve performance. 
Having an initial size for the labels ensures that the cache is initialized properly. 


The last remaining part is the test program, shown in Listing 17-5. The majority of it just 
creates arrays of Book objects. It reuses the NamedVector class from Listing 17-1 to help create 
the tree branches. The code lines necessary for changing the tree cell renderer are boldfaced. 
Running the program demonstrates the custom renderer, as shown earlier in Figure 17-10. 
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Listing 17-5. Using the Custom Book Cell Renderer 


import javax.swing.*; 
import javax.swing.tree.*; 
import java.awt.*; 

import java.util.*; 


public class BookTree ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("Book Tree"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
Book javaBooks[] = 1 
new Book("Core Java 2", "Horstmann/Cornell", 49.99f), 
new Book("Effective Java", "Bloch", 34.99f), 
new Book("Java Collections", "Zukowski", 49.95f) 


E 
Book netBooks[] = 4 

new Book("Beginning VB .NET 1.1 Databases", "Maharry", 49.99f), 

new Book("Beginning VB.NET Databases", "Willis", 39.99f) 
E 
Vector<Book> javaVector = new NamedVector<Book>("Java Books", javaBooks); 
Vector<Book> netVector = new NamedVector<Book>(".NET Books", netBooks); 
Object rootNodes[] = (javaVector, netVector); 
Vector<Object> rootVector = new NamedVector<0bject>("Root", rootNodes); 
JTree tree = new JTree(rootVector); 
TreeCellRenderer renderer = new BookCellRenderer(); 
tree.setCellRenderer(renderer); 
JScrollPane scrollPane = new JScrollPane(tree); 
frame.add(scrollPane, BorderLayout.CENTER); 
frame.setSize(300, 300); 
frame.setVisible(true); 


) 
5 
Event0Queue.invokeLater(runner); 
y 
) 


Note Don't worry about the details of DefaultMutableTreeNode just yet. Unless otherwise directed, all the 
nodes of every tree are a DefaultMutableTreeNode. Each array element placed in a Vector in Listing 17-5 
defines the data for that specific node. This data is then stored in the userObject property of its 
DefaultMutableTreeNode 
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Working with Tree Tooltips 


If you want a tree to display tooltips for the nodes, you must register the component with the 

ToolTipManager. Ifyou don't register the component, the renderer will never get the opportunity 
to display tooltips. The renderer displays the tip, not the tree, so setting tooltip text for the tree 
isignored. The following line shows how you to register a specific tree with the ToolTipManager. 


ToolTipManager.sharedInstance().registerComponent (aTree); 


Once you've notified the Too1TipManager that you want the tree to display tooltip text, you 
must tell the renderer what text to display. Although you can directly set the text with the 
following lines, this results in a constant setting for all nodes. 


DefaultTreeCellRenderer renderer = (DefaultTreeCellRenderer)aTree.getCellRenderer(); 
renderer.setToolTipText("Constant Tool Tip Text"); 


Instead of providing a constant setting, one alternative is to provide the renderer with a table 
of tooltip strings so that the renderer can determine at runtime the string to display as the tooltip 
text. The renderer in Listing 17-6 is one such example that relies on a java.util.Dictionary 
implementation (like a Hashtable) to store a mapping from nodes to tooltip text. If a tip exists 
for a specific node, the renderer associates the tip with it. 


Listing 17-6. Tooltip Cell Renderer 


import javax.swing.*; 
import javax.swing.tree.*; 
import java.awt.*; 

import java.util.*; 


public class ToolTipTreeCellRenderer implements TreeCellRenderer ( 
DefaultTreeCellRenderer renderer = new DefaultTreeCellRenderer(); 
Dictionary tipTable; 


public ToolTipTreeCellRenderer (Dictionary tipTable) ( 
this.tipTable = tipTable; 
J 


public Component getTreeCellRendererComponent(JTree tree, Object value, 
boolean selected, boolean expanded, boolean leaf, int row, 
boolean hasFocus) ( 
renderer.getTreeCellRendererComponent(tree, value, selected, expanded, 
leaf, row, hasFocus); 
if (value != null) £ 
Object tipKey; 
if (value instanceof DefaultMutableTreeNode) f 
tipKey = ((DefaultMutableTreeNode)value).getUser0bject(); 
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) else £ 
tipKey = tree.convertValueToText(value, selected, expanded, leaf, 
row, hasFocus); 


J 
renderer.setToolTipText((String)tipTable.get(tipKey)); 


J 


return renderer; 


J 
y 


Note The example in Listing 17-6 takes advantage of the JTree method public String 
convertValueToText(Object value, boolean selected, boolean expanded, boolean leaf, 
int row boolean hasFocus) to convert the tree node value to a text string. The value parameter ¡s 
normally a DefaultMutableTreeNode, described later in this chapter. When the value parameter is not a 
DefaultMutableTreeNode, using convertValueToText() allows the renderer to support other types of 
tree nodes. 


Using the new ToolTipTreeCellRenderer class simply involves creating the Properties list, 
filling it with tooltip text for the necessary nodes, and then associating the renderer with the 
tree. Figure 17-11 shows the renderer in action. 
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Figure 17-11. A JTree with tooltips, using the new ToolTipTreeCellRenderer 


The complete sample program used to generate the screen in Figure 17-11 is shown next 
in Listing 17-7. This tree uses the list of system properties as the tree nodes. The tooltip text is 
the current setting for the specific property. When using the Too1TipTreeCellRenderer, be sure 
to register the tree with the Too1TipManager. 


Listing 17-7. Using a Tooltip Cell Renderer 


import javax.swing.*; 
import javax.swing.tree.*; 
import java.awt.*; 

import java.util.*; 
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public class TreeTips ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() £ 
public void run() £ 
JFrame frame = new JFrame("Tree Tips"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
Properties props = System.getProperties(); 
JTree tree = new JTree(props); 
Too1TipManager.sharedInstance().registerComponent (tree); 
TreeCellRenderer renderer = new ToolTipTreeCellRenderer(props); 
tree.setCellRenderer(renderer); 
JScrollPane scrollPane = new JScrollPane(tree); 
frame.add(scrollPane, BorderLayout.CENTER); 
frame.setSize(300, 150); 
frame.setVisible(true); 
J 
5 
EventQueue.invokelLater(runner); 
y 
J 


Although this example creates a new tree cell renderer, the behavior is only customizing 
what has already been done for the Default TreeCellRenderer. Instead of needing to configure 
the icons and text yourself, let the default renderer do it for you. Then add the tooltip text. 


Editing Tree Nodes 


In addition to supporting individualized tree cell renderers, JTree components can be editable, 
allowing users to change the contents of any node of the tree. By default, trees are read-only. 
To make a tree editable, just change the editable property setting to return true: 


alree.setEditable(true); 


By default, the editor is a text field. There is also built-in support for picking choices from 
combo boxes or check boxes. Ifyou prefer, you can create a customized editor for a tree, just as 
you can create a custom cell renderer. 


Note Unfortunately, the built-in check box editor works better within a table than within a tree, where the 
column label is the name and the value ¡is the cell. 


Figure 17-12 shows a tree using the default editor. To enable the editor, select a node, 
and then double-click it. IHfthe node isn't a leaf node, selecting it will also display or hide the 
node's children. 


643 


644 


CHAPTER 17 TREES 


lx 
JTree e 

9 UH [colours 

Q blue 

Q violet 

Q red 


Q yellow 


1 


4] 


Figure 17-12. An editable JTree with the default editor 


A series of classes is available to support editing tree nodes. Many are shared with the 
JTable component because both can support editable cells. The CellEditor interface forms the 
basis for the TreeCellEditor interface. Any editor implementation for a JTree must implement 
the TreeCellEditor interface. The DefaultCel1Editor (which extends AbstractCellEditor) 
offers one such editor implementation, and the DefaultTreeCellEditor offers another. Let's 
now look at these interfaces and classes in more detail. 


CellEditor Interface 


The CellEditor interface defines the necessary basics for any editor used with a JTree or JTable, 
as well as for any third-party components that need an editor. Besides defining howto manage 
a list of CellEditorListener objects, the interface describes how to determine if a particular 
node or cell is editable and what the new value is after the editor has changed its value. 


public interface CellEditor ( 
// Properties 
public Object getCellEditorvalue(); 
// Listeners 
public void addCellEditorListener(CellEditorlListener 1); 
public void removeCellEditorlListener(CellEditorListener 1); 
// Other methods 
public void cancelCellEditing(); 
public boolean isCellEditable(EventObject event); 
public boolean shouldSelectCell(EventObject event); 
public boolean stopCellEditing(); 


TreeCellEditor Interface 


The TreeCellEditor interface works similarly to the TreeCellRenderer interface. However, the 
getXXXComponent () method does not have an argument that tells the editor it has the input 
focus, because in the case of an editor, it must already have the input focus. Any class imple- 
menting the TreeCellEditor interface can serve as an editor for your JTree. 


public interface TreeCellEditor implements CellEditor ( 
public Component getTreeCellEditorComponent(JTree tree, Object value, 
boolean isSelected, boolean expanded, boolean leaf, int row); 
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DefaultCellEditor Class 


The DefaultCellEditor class serves as an editor for both tree nodes and table cells. The class 
allows you to easily provide a text editor, combo box editor, or check box editor to modify the 
contents of a node or cell. 

The DefaultTreeCellEditor class, described next, uses this class to provide an editor for a 
customized text field, maintaining the appropriate node-typeicon based on a TreeCellRenderer. 


Creating a DefaultCellEditor 


When you create a DefaultCellEditor instance, you provide the JTextField, JComboBox, or 
JCheckBox to use as the editor. 


public DefaultCellEditor(JTextField editor) 
JTextField textField = new JTextField(); 
TreeCellEditor editor = new DefaultCellEditor(textField); 


public DefaultCellEditor(JComboBox editor) 

public static void main (String args[]) ( 
JComboBox comboBox = new JComboBox(args); 
TreeCellEditor editor = new DefaultCellEditor(comboBox); 


e 


public DefaultCellEditor(JCheckBox editor) 
JCheckBox checkBox = new JCheckBox(); 
TreeCellEditor editor = new DefaultCellEditor(checkBox); 


With a JTree, you should use the DefaultTreeCellEditor if you want a JTextField editor. 
That text field will share the same font and use the appropriate editor border for the tree. When 
a JCheckBox is used as the editor, the node for the tree should be either a Boolean value or a 
String that can be converted to a Boolean. (If you are unfamiliar with conversion from String 
to Boolean, see the Javadoc for the Boolean constructor that accepts a String.) 

After creating an editor, you tell the tree to use it with a call similar to tree. 
setCellEditor(editor). And don't forget to make the tree editable with tree. 
setEditable(true). For instance, if you wanted an editable combo box as your editor, 
the following source code would work: 


JTree tree = new JTree(...); 

tree.setEditable(true); 

String elements[] = £ "Root", "chartreuse", "rugby", "sushi") ; 
JComboBox comboBox = new JComboBox(elements); 
comboBox.setEditable(true); 

TreeCellEditor editor = new DefaultCellEditor(comboBox); 
tree.setCellEditor(editor); 


This code produces the screen shown in Figure 17-13 when editing the basketball node. 
Notice that there is no icon to indicate the type of node being edited. This is rectified with the 
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DefaultTreeCellEditor class. The DefaultCellEditor is primarily for use within a JTable, not 
a JTree. 
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Figure 17-13. An editable JTree with a JComboBox editor 


Caution When you use a noneditable JComboBox as the cell editor, if the set of choices doesn't include 
the original node setting, it's impossible to get back to the original setting once the node value changes. 


To see how awkward the appearance of a JCheckBox is with the DefaultCellEditor as a 
TreeCellEditor, take a look at Figure 17-14. 
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Figure 17-14. An editable JTree with a JCheckBox editor 


Figure 17-14 uses the following source: 


Object array[] = 
[Boolean.TRUE, Boolean.FALSE, "Hello"); // Hello will map to false 
JTree tree = new JTree(array); 
tree.setEditable(true); 
tree.setRootVisible(true); 
JCheckBox checkBox = new JCheckBox(); 
TreeCellEditor editor = new DefaultCellEditor(checkBox) ; 
tree.setCellEditor(editor); 


Note Use of the JCheckBox with the DefaultCel1Editor isn't recommended with a JTree. See the 
“Creating a Better Check Box Node Editor” section later in this chapter for an implementation that's more 
appropriate for a tree. 
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The awkwardness of the JCheckBox editor and custom text field editor within the 
DefaultTreeCellEditor leaves the JComboBox as the only TreeCel1lEditor you'll get from 
DefaultCellEditor. However, you still might want to place the combo box editor within a 
DefaultTreeCellEditor to display the appropriate type icon next to the node. 


DefaultCellEditor Properties 


The DefaultCellEditor has only three properties, which are listed in Table 17-4. The editor can 
be any AWT component, not just a lightweight Swing component. Keep in mind the hazards of 
mixing heavyweight and lightweight components, if you do choose to use a heavyweight compo- 
nent as the editor. If you want to find out what the current setting is for the editor component, 
ask for the setting ofthe cellEditorValue property. 


Table 17-4. DefaultCellEditor Properties 


Property Name Data Type Access 

cellEditorValue Object Read-only 
clickCountToStart int Read-write 
component Component Read-only 


DefaultTreeCellEditor Class 


The DefaultTreeCellEditor class is the TreeCellEditor that is automatically used by a 
JTree when you make a tree editable but you don't associate an editor with that tree. The 
DefaultTreeCellEditor combines the icons from a TreeCellRenderer with a TreeCellEditor 
to return a combined editor. 

The default component used as the editoris a JTextField. This text editor is special in that 
it tries to limit its height to the original cell renderer and prefers the font of the tree so that it 
won't appear out of place. The editor uses two public inner classes to accomplish this feat: 
DefaultTreeCellEditor.EditorContainer and DefaultTreeCellEditor.DefaultTextField. 

There are two constructors for DefaultTreeCellEditor. Normally, you don't need to call 
the first constructor because it's automatically created for you by the user interface when it 
determines that the node is editable. However, it may be necessary if you want to customize 
the default editor in some manner. 


public DefaultTreeCellEditor(JTree tree, DefaultTreeCellRenderer renderer) 

JTree tree = new JTree(...); 

DefaultTreeCellRenderer renderer = (DefaultTreeCellRenderer)tree.getCellRenderer(); 
TreeCellEditor editor = new DefaultTreeCellEditor(tree, renderer); 


public DefaultTreeCellEditor(JTree tree, DefaultTreeCellRenderer renderer, 
TreeCellEditor editor) 
public static void main (String args[]) ( 
JTree tree = new JTree(...); 
DefaultTreeCellRenderer renderer = 
(DefaultTreeCellRenderer)tree.getCellRenderer(); 
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JComboBox comboBox = new JComboBox(args); 
TreeCellEditor comboEditor = new DefaultCellEditor(comboBox) ; 
TreeCellEditor editor = new DefaultTreeCellEditor(tree, renderer, comboEditor); 


Creating a Proper ComboBox Editor for a Tree 


As Figure 17-13 showed, using a JComboBox as the TreeCellEditor via a DefaultCellEditor 
doesn't place the appropriate node-type icon next to the editor. If you want the icons present, 
you need to combine the DefaultCellEditor with a DefaultTreeCellEditor to get an editor 
with both an icon and an editor. It's really not as hard as it sounds. It just involves two extra 
steps: getting the renderer for the tree (from which to get the icons), and then combining the 
icon with the editor to get a new editor. The following source demonstrates this: 


JTree tree = new JTree(); 

tree.setEditable(true); 

DefaultTreeCellRenderer renderer = (DefaultTreeCellRenderer)tree.getCellRenderer(); 
String elements[] = £ "Root", "chartreuse", "rugby", "sushi") ; 

JComboBox comboBox = new JComboBox(elements); 

comboBox.setEditable(true); 

TreeCellEditor comboEditor = new DefaultCellEditor(comboBox) ; 

TreeCellEditor editor = new DefaultTreeCellEditor(tree, renderer, comboEditor); 
tree.setCellEditor(editor); 


The improved output is shown in Figure 17-15. 


PENTI lo 


Figure 17-15. An editable JTree with a JComboBox editor and tree icons 


Creating an Editor Just for Leaf Nodes 


In some cases, you will want only the leafnodes ofa tree to be editable. Returningnull from the 
getTreeCellEditorComponent () request effectively makes a node not editable. Unfortunately, 
this causes a NullPointerException to be thrown by the user interface class. 

Instead of returning null, you can override the default behavior ofthe public boolean 
isCellEditable(EventObject object) method, which is part ofthe CellEditor interface. Ifthe 
original return value is true, you can do an additional check to see ifthe selected node of the 
tree is a leaf. Nodes of a tree implement the TreeNode interface (described later in this chapter 
in the “TreeNode Interface” section ). This interface happens to have the method public 
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boolean isLeaf(), which provides the answer you're looking for. The class definition for a 
leaf node cell editor is shown in Listing 17-8. 


Listing 17-8. Tree Cell Editor for Leaf Nodes 


import javax.swing.*; 

import javax.swing.tree.*; 
import java.awt.*; 

import java.util.EventObject; 


public class LeafCellEditor extends DefaultTreeCellEditor ( 


public LeafCellEditor(JTree tree, DefaultTreeCellRenderer renderer) ( 
super(tree, renderer); 


J 


public LeafCellEditor(JTree tree, DefaultTreeCellRenderer renderer, 
TreeCellEditor editor) ( 
super(tree, renderer, editor); 


J 


public boolean isCellEditable(EventObject event) ( 
// Get initial setting 
boolean returnValue = super.isCellEditable(event); 
// 1f still possible, check if current tree node is a leaf 
if (returnValue) ( 
Object node = tree.getlastSelectedPathComponent(); 
if ((node != null) 88. (node instanceof TreeNode)) f 
TreeNode treeNode = (TreeNode)node; 
returnValue = treeNode.isleaf(); 
J 
y 
return returnValue; 
E 
J 


You use the LeafCellEditor in the same way as a DefaultTreeCellRenderer. It requires a 
JTree and DefaultTreeCellRenderer for its constructor. In addition, it supports an optional 
TreeCellEditor. If one isn't provided, a JTextField is used as the editor. 


JTree tree = new JTree(); 

tree.setEditable(true); 

DefaultTreeCellRenderer renderer = (DefaultTreeCellRenderer)tree.getCellRenderer(); 
TreeCellEditor editor = new LeafCellEditor(tree, renderer); 
tree.setCellEditor(editor); 


649 


650 


CHAPTER 17 TREES 


CellEditorListener Interface and ChangeEvent Class 


Before exploring the creation of a complete TreeCellEditor, take a look at the CellEditorListener 
interface definition. The interface contains two methods that are used with a CellEditor. 


public interface CellEditorlistener implements EventListener ( 
public void editingCanceled(ChangeEvent changeEvent); 
public void editingStopped(ChangeEvent changeEvent); 


J 


The editor calls the editingCanceled() method of the registered listeners to signal that the 
editing of the node's value has been aborted. The editingStopped() method is called to signal 
the completion of an editing session. 

Normally, it's not necessary to create a CellEditorListener. However, when creating a 
TreeCellEditor (or any CellEditor), it is necessary to manage a list of its listeners and notify 
those listeners when necessary. Thankfully, this is managed for you automatically with the 
help ofthe AbstractCellEditor. 


Creating a Better Check Box Node Editor 


Using the JCheckBox editor provided by the DefaultCellEditor class isn't a good option when 
working with a JTree. Although the editor can be wrapped into a DefaultTreeCellEditor to get 
the appropriate tree icon next to it, you can't display text within the check box (that is, besides 
true or false). Other text strings can be displayed within the tree, but once a node is edited, the 
text label for the edited node can only be true or false. 

To have an editable check box with a text label as the tree cell editor, you must create your 
own. The complete process involves creating three classes—a data model for each node of the 
tree, a tree cell renderer to render this custom data structure, and the actual editor—plus a test 
program to connect them all. 


Note The renderer and editor created here will support check-box-like data only for editing leaf nodes. If 
you want to support check boxes for nonleaf nodes, you need to pull out the code that checks for leaf nodes. 


Creating the CheckBoxNode Class 


The first class to be created is for the data model for each leaf node of the tree. You could use 
the same data model as the JCheckBox class, but that includes extraneous information at each 
node that you don't need. The only information necessary is the selected state of the node and 
its text label. With the addition of some setter and getter methods for the state and label, the 
class is basically defined, as shown in Listing 17-9. The other classes are not quite this easy to 
formulate. 
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Listing 17-9. Custom Node Data for a JTree 


public class CheckBoxNode ( 

String text; 

boolean selected; 

public CheckBoxNode(String text, boolean selected) ( 

this.text = text; 
this.selected = selected; 

) 

public boolean isselected() ( 
return selected; 
) 
public void setSelected(boolean newValue) ( 
selected = newValue; 
) 
public String getText() ( 
return text; 
) 
public void setText(String newValue) £ 
text = newValue; 
) 
public String toString() ( 

return getClass().getName() + "[" + text + "/" + selected + "]"; 


y 
J 


Creating the CheckBoxNodeRenderer Class 


The renderer will have two parts. For nonleaf nodes, you can use the DefaultTreeCellRenderer 
because those nodes aren't meant to be CheckBoxNode elements. Forthe renderer for leaf nodes 
of type CheckBoxNode, you need to map the data structure into an appropriate renderer. Because 
these nodes contain a selection state and a text label, the JCheckBox acts as a good renderer for 
the leaf nodes. 

The easier of the two to explain is the nonleaf node renderer. In this example, it simply 
configures a DefaultTreeCellRenderer as it would normally; nothing special is done. 

The renderer for the leaf nodes requires a bit more work. Before even configuring any nodes, 
you need to make it look like the default renderer. The constructor acquires the necessary fonts 
and various colors from the look and feel for the renderer, ensuring that the two renderers will 
appear similar. 

The definition for the tree cell renderer, class CheckBoxNodeRenderer, is shown in Listing 17-10. 
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Listing 17-10. Custom Node Renderer for a JTree 


import javax.swing.*; 

import javax.swing.border.*; 
import javax.swing.tree.*; 
import java.awt.*; 


public class CheckBoxNodeRenderer implements TreeCellRenderer £ 

private JCheckBox leafRenderer = new JCheckBox(); 

private DefaultTreeCellRenderer nonLeafRenderer = new DefaultTreeCellRenderer(); 

Color selectionBorderColor, selectionForeground, selectionBackground, 
textForeground, textBackground; 


protected JCheckBox getleafRenderer() ( 
return leafRenderer; 


J 


public CheckBoxNodeRenderer() ( 

Font fontValue; 

fontValue = UlManager.getFont("Tree.font"); 

if (fontValue != null) € 
leafRenderer.setFont(fontValue); 

) 

Boolean booleanValue = 
(Boolean)UIManager .get("Tree.drawsFocusBorderAroundIcon"); 

leafRenderer.setFocusPainted((booleanValue != null) 88 
(booleanValue.booleanValue())); 


selectionBorderColor = UIManager.getColor("Tree.selectionBorderColo1"); 
selectionForeground = UlManager.getColor("Tree.selectionForeground”); 
selectionBackground = UlManager.getColor("Tree.selectionBackground"); 
textForeground = UlManager.getColor("Tree.textForeground"); 
textBackground = UIManager.getColor("Tree.textBackground"); 

) 


public Component getTreeCellRendererComponent(JTree tree, Object value, 
boolean selected, boolean expanded, boolean leaf, int row, boolean hasFocus) ( 


Component returnValue; 
if (leaf) ( 


String stringValue = tree.convertValueToText(value, selected, expanded, 
leaf, row, false); 

leafRenderer.setText(stringValue); 

leafRenderer.setSelected(false); 


leafRenderer.setEnabled(tree.isEnabled()); 
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if(selected) f 
leafRenderer.setForeground(selectionForeground); 
leafRenderer.setBackground(selectionBackground); 

y else [ 
leafRenderer.setForeground(textForeground); 
leafRenderer.setBackground(textBackground); 


J 


if ((value != null) 88 (value instanceof DefaultMutableTreeNode)) f 
Object user0bject = ((DefaultMutableTreeNode)value).getUser0bject(); 
if (user0bject instanceof CheckBoxNode) ( 

CheckBoxNode node = (CheckBoxNode)user0Object; 
leafRenderer.setText(node.getText()); 
leafRenderer.setSelected(node.isselected()); 
) 
) 


returnValue = leafRenderer; 
) else £ 
returnValue = nonLeafRenderer.getTreeCellRendererComponent(tree, value, 
selected, expanded, leaf, row, hasFocus); 


, 
return returnValue; 
) 
) 


Note The getLeafRenderer() method is a helper method you'I! need in the editor. 


Creating the CheckBoxNodeEditor Class 


The CheckBoxNodeEditor class is the last part of creating a better check box node editor. It serves 
as the TreeCellEditor implementation, allowing you to support editing of trees whose leaf 
node datais oftype CheckBoxNode. The TreeCellEditor interface is an extension ofthe CellEditor 
implementation, so you must implement the methods of both interfaces. You can't extend 
DefaultCellEditor or DefaultTreeCellEditor, because they would require you to use the 
JCheckBox editor implementation they provide, instead of the new one you're creating here. 
However, you can extend AbstractCellEditor and add the necessary TreeCellEditor interface 
implementation. An AbstractCellEditor manages the list of CellEditorListener objects for 
you and has methods to notify the list of listeners upon either stopping or canceling editing. 

Because the editor acts as the renderer, you'll need to use the earlier 
CheckBoxNodeRenderer to get the basic renderer appearance. This will ensure that the editor 
appears similar to the renderer. Because the renderer for the leaf nodes will be a JCheckBox, this 
works perfectly well to enable you to change the node state. The editor JCheckBox will be active 
and changeable, allowing a user to change from a selected state to an unselected state, and vice 
versa. Ifinstead the editor were the standard DefaultTreeCellRenderer, you would need to 
manage the creation of selection changes. 
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Now that the class hierarchy has been set up, the first method to examine is the public 
Object getCellEditorvalue() method of CellEditor. The purpose of this method is to convert 
the data as stored within the node editor into the data as stored within the node. The user interface 
calls this method to get the editor's value after it has determined that the user has successfully 
changed the data within the editor. In this method, you need to create a new object each time. 
Otherwise, the same node will be in the tree multiple times, causing all nodes to be equal to the 
renderer for the last edited node. To convert the editor to the data model, it's necessary to ask 
the editor what its current label and selected state are, and then create and return a new node. 


public Object getCellEditorvalue() ( 
JCheckBox checkbox = renderer.getlLeafRenderer(); 
CheckBoxNode checkBoxNode = 
new CheckBoxNode(checkbox.getText(), checkbox.isSelected()); 
return checkBoxNode; 


J 


Note it's not the job of the editor to directly access the node within the tree to update it. The 
getCellEditorValue() method returns the appropriate node object so that the user interface can 
notify the tree of any changes. 


Ifyou were to implement the CellEditor interface yourself, you would also need to manage 
the list of CellEditorListener objects yourself. You would need to manage the list with the 
addCellEditorListener() and removeCellEditorListener() methods, and provide methods that 
notify the list of listeners for each method in the interface. But, because you'll be subclassing 
AbstractCellEditor, it's not necessary to do this yourself. You just need to know that the class 
provides fireEditingCanceled() and fireEditingStopped() methods in order to notify the 
listener list at the appropriate times. 

The next CellEditor method, cancelCellEditing(), is called when a new node of the tree 
is selected, announcing that the editing process of the prior selection has stopped and any 
interim update has been aborted. The method is capable of doing anything, such as destroying 
any necessary interim objects used by the editor. However, what the method should do is call 
fireEditingCanceled(); this ensures that any registered CellEditorListener objects are notified of 
the cancellation. The AbstractCellEditor does this for you. Unless you need to do some interim 
operations, it's not necessary to override this behavior. 

The stopCellEditing() method of the CellEditor interface returns a boolean. This method is 
called to see if editing of the current node can stop. If any validation needs to be done to deter- 
mine whether editing can stop, you would check here. For the CheckBoxNodeEditor in this 
example, no validation check is necessary. Therefore, editing can always stop, allowing the 
method to always return true. 

You would call the fireEditingStopped() method when you want to have the editor stop 
editing. For instance, ifthe editor were a text field, pressing Enter within the text field could act 
as the signal to stop editing. In the case of the JCheckBox editor, selection could act as a signal 
to stop the editor. If fireEditingStopped() isn't called, the tree data model isn't updated. 

To stop editing after selection of the JCheckBox, attach an ItemListener to it. 
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ItemListener itemlListener = new ItemListener() f 
public void itemStateChanged(ItemEvent itemEvent) £ 
if (stopCellEditing()) ( 
fireEditingStopped(); 
) 
) 
5 


editor.addItemListener(itemListener); 


The next method of the CellEditor interface to look atis public boolean 
isCellEditable(EventObject event). The method returns a boolean to state whether the node 
at the source of the event is editable. To find out ifthe event happens at a particular node, you 
need a reference to the tree where the editor is to be used. You can add this requirement to the 
constructor of the editor. 

To find out which nodeis at a specific position during an event, you can ask the tree for the 
path of nodes to the event location. The path is returned as a TreePath object, which is examined 
again later in this chapter in the “TreePath Class” section. The last component ofthe tree path 
is the specific node where the event happened. Itis this node that you must check to determine 
if it's editable. Ifitis editable, the method returns true; if it isn't editable, false is returned. In 
the case of the tree to be created here, a node is editable ifit's a leaf node and it contains 
CheckBoxNode data. 


JTree tree; 


public CheckBoxNodeEditor(JTree tree) ( 
this.tree = tree; 


li 


public boolean isCellEditable(EventObject event) ( 
boolean returnValue = false; 
if (event instanceof MouseEvent) f 
MouseEvent mouseEvent = (MouseEvent)event; 
TreePath path = tree.getPathForLocation(mouseEvent.getX(), mouseEvent.getY()); 
if (path != null) € 
Object node = path.getLastPathComponent(); 
if ((node != null) 88 (node instanceof DefaultMutableTreeNode)) f 
DefaultMutableTreeNode treeNode = (DefaultMutableTreeNode)node; 
Object userObject = treeNode.getUser0bject(); 
returnValue = ((treeNode.isLeaf()) 38 (userObject instanceof CheckBoxNode)); 
) 
) 
) 
return returnValue; 


J 


The shouldSelectCel11() method of the CellEditor interface allows you to decide whether 
anodeis selectable. For the editor in this example, all editable cells should be selectable. However, 
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this method allows you to look at a specific node to see if it can be selected. By default, 
AbstractCellEditor returns true for this method. 

The remaining method, getTreeCel1EditorComponent(), is from the TreeCellEditor inter- 
face. You'll need a reference to a CheckBoxNodeRenderer to get and use that as the editor. There 
are two minor changes besides just passing through all the arguments. Editors should always 
be selected and have the input focus. This simply forces two arguments to always be true. 
When the node is selected, the background is filled in. When focused, a border surrounds the 
editor when UlManager.get("Tree.drawsFocusBorderAroundIcon") reports true. 


CheckBoxNodeRenderer renderer = new CheckBoxNodeRenderer (>); 
public Component getTreeCellEditorComponent(JTree tree, Object value, 
boolean selected, boolean expanded, boolean leaf, int row) ( 


// Editor always selected / focused 
return renderer.getTreeCellRendererComponent(tree, value, true, expanded, leaf, 
row, true); 


Listing 17-11 shows everything put together, presenting the complete CheckBoxNodeEditor 
class source. 


Listing 17-11. Custom Node Editor for a JTree 


import javax.swing.*; 

import javax.swing.event.*; 
import javax.swing.tree.*; 
import java.awt.*; 

import java.awt.event.*; 
import java.util.EventObject; 


public class CheckBoxNodeEditor extends AbstractCellEditor implements 
TreeCellEditor ( 


CheckBoxNodeRenderer renderer = new CheckBoxNodeRenderer(); 
ChangeEvent changeEvent = null; 
JTree tree; 


public CheckBoxNodeEditor(JTree tree) ( 
this.tree = tree; 


) 


public Object getCellEditorvalue() ( 
JCheckBox checkbox = renderer.getlLeafRenderer(); 
CheckBoxNode checkBoxNode = 
new CheckBoxNode(checkbox.getText(), checkbox.isSelected()); 
return checkBoxNode; 


) 
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public boolean isCellEditable(EventO0bject event) ( 
boolean returnValue = false; 
if (event instanceof MouseEvent) ( 
MouseEvent mouseEvent = (MouseEvent)event; 
TreePath path = tree.getPathForLocation(mouseEvent.getX(), mouseEvent.getY()); 
if (path != null) £ 
Object node = path.getlLastPathComponent(); 
if ((node != null) 88 (node instanceof DefaultMutableTreeNode)) f 
DefaultMutableTreeNode treeNode = (DefaultMutableTreeNode)node; 
Object userObject = treeNode.getUser0bject(); 
returnValue = ((treeNode.isleaf()) 88 
(user0bject instanceof CheckBoxNode)); 
i 
E 
h 
return returnValue; 


h 


public Component getTreeCellEditorComponent(JTree tree, Object value, 
boolean selected, boolean expanded, boolean leaf, int row) ( 


Component editor = renderer.getTreeCellRendererComponent(tree, value, true, 
expanded, leaf, row, true); 


// Editor always selected / focused 
ItemListener itemListener = new ItemListener() ( 
public void itemStateChanged(ItemEvent itemEvent) ( 
if (stopCellEditing()) ( 
fireEditingStopped(); 
) 
J 
5 
if (editor instanceof JCheckBox) ( 
((cCheckBox)editor).addItemListener(itemListener); 
y 


return editor; 


Note Notice that there's no direct change of the data in the tree node. It's not the role of the editor to 
change the node. The editor only gets the new node value, returning it with getCel1EditorValue(). 
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Creating the Test Program 


The test program in Listing 17-12 consists primarily of creating the CheckBoxNode elements. 
In addition to creating the tree data, the tree must have the renderer and editor associated with 
it and be made editable. 


Listing 17-12. Using the Custom Node Editor 


import javax.swing.*; 
import javax.swing.tree.*; 
import java.awt.*; 

import java.util.Vector; 


public class CheckBoxNodeTreeSample £ 
public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("CheckBox Tree"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


CheckBoxNode accessibility0ptions[] = ( 
new CheckBoxNode("Move system caret with focus/selection changes", false), 
new CheckBoxNode("Always expand alt text for images", true) 
$ 
CheckBoxNode browsingOptions[] = ( 
new CheckBoxNode("Notify when downloads complete", true), 
new CheckBoxNode("Disable script debugging", true), 
new CheckBoxNode("Use AutoComplete", true), 
new CheckBoxNode("Browse in a new process", false) 
$ 
Vector<CheckBoxNode> accessVector = 
new NamedVector<CheckBoxNode>("Accessibility", accessibility0ptions); 
Vector<CheckBoxNode> browseVector = 
new NamedVector<CheckBoxNode>("Browsing", browsing0ptions); 
Object rootNodes[] = faccessVector, browseVector); 
Vector<Object> rootVector = new NamedVector<0bject>("Root", rootNodes); 
JTree tree = new JTree(rootVector); 


CheckBoxNodeRenderer renderer = new CheckBoxNodeRenderer(); 
tree.setCellRenderer(renderer); 


tree.setCellEditor(new CheckBoxNodeEditor(tree)); 
tree.setEditable(true); 
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JScrollPane scrollPane = new JScrollPane(tree); 
frame.add(scrollPane, BorderLayout.CENTER); 
frame.setSize(300, 150); 
frame.setVisible(true); 
) 
$ 
EventQueue.invokeLater(runner); 
) 
) 


Running the program and selecting a CheckBoxNode will enable the editor. After the editor 
is enabled, selecting the editor again causes the state ofthe node within the tree to change. The 
editor stays enabled until a different tree node is selected. Figure 17-16 shows an example of 
the editor in use. 
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Figure 17-16. The new CheckBoxNodeEditor in action 


Working with the Nodes of the Tree 


When you create a JTree, the type of objects at any spot in the tree can be any Object. There 
is no requirement that the nodes of the tree implement any interface or subclass any class. 
Nevertheless, the Swing component libraries provide a pair of interfaces and one class for 
working with tree nodes. The default data model for the tree, DefaultTreeModel, uses these 
interfaces and the class. However, the tree data model interface, TreeModel, permits any type 
of object to be a tree node. 

The base interface for nodes is TreeNode, which defines a series of methods describing a read- 
only, parent-children aggregation relationship. Expanding on TreeNode is the MutableTreeNode 
interface, which allows you to programmatically connect nodes and store information at each 
node. The class that implements the two interfaces is the DefaultMutableTreeNode class. 
Besides implementing the methods of the two interfaces, the class provides a set of methods 
for traversing the tree and inquiring about the state of various nodes. 

Keep in mind that although these node objects are available, much work can be still 
performed without involving these interfaces and classes, as previously shown in this chapter. 


TreeNode Interface 


The TreeNode interface describes one possible definition for an individual part of a tree. It's used 
by one implementation of TreeModel, the DefaultTreeModel class, to store references to the 
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hierarchical data that describes a tree. The interface allows you to find out which node isthe parent 
to the current node, as well as get information about the set of child nodes. When the parent 
node is null, the node is the root of a tree. 


public interface TreeNode ( 
// Properties 
public boolean getAllowsChildren(); 
public int getChildCount(); 
public boolean isLeaf(); 
public TreeNode getParent(); 
// Other methods 
public Enumeration children(); 
public TreeNode getChildAt(int childIndex); 
public int getIndex(TreeNode node); 


Note Normally, only nonleaf nodes allow children. However, security restrictions may limit nonleaf nodes 
from having children, or at least showing them. Imagine a directory tree in which you don't have read access 
to a particular directory. Although the directory is a nonleaf node, it can't have child nodes because you don't 
have access to find out what those children are. 


MutableTreeNode Interface 


Although the TreeNode interface allows you to retrieve information about a hierarchy of tree 
nodes, it doesn't allow you to create the hierarchy. TreeNode just provides you access to a read- 
only tree hierarchy. On the other hand, the MutableTreeNode interface allows you to create the 
hierarchy and store information at a specific node within the tree. 


public interface MutableTreeNode implements TreeNode ( 
// Properties 

public void setParent(MutableTreeNode newParent); 

public void setUser0bject(Object object); 

// Other methods 

public void insert(MutableTreeNode child, int index); 

public void remove(MutableTreeNode node); 

public void remove(int index); 

public void removeFromParent(); 


When creating the hierarchy of tree nodes, you can either create children nodes and add 
them to their parent or create parent nodes and add children. To associate a node with a parent 
node, you set its parent with setParent (). Using insert () allows you to add children to a parent 
node. The arguments for the insert () method include an index argument. This index represents 
the position within the set of children to add the child node provided. The index is zero-based, 
so an index of zero will add the node as the first child ofthe tree. Adding a node as the last child, 
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instead of the first, requires you to ask the node with getChildCount () how many children it 
already has and then add 1: 


mutableTreeNode.insert(childMutableTreeNode, mutableTreeNode.getChildCount()+1); 


At least for the DefaultMutableTreeNode class described next, setParent () sets a node to be 
the parent of a child node, even though it doesn't make the child node a child of the parent. In 
other words, don't call setParent() yourself; call insert(), and it will set the parent accordingly. 


Caution The insert() method doesn't allow circular ancestry, where the child node to be added is an 
ancestor to the parent. Ifthat's attempted, an I11egalArgumentException will be thrown. 


DefaultMutableTreeNode Class 


The DefaultMutableTreeNode class provides an implementation of the MutableTreeNode interface 
(which implements the TreeNode interface). When you're creating a tree from a Hashtable, an 
array, or a Vector constructor, JTree automatically creates the nodes as a set of type 
DefaultMutableTreeNode. If, on the other hand, you want to create the nodes yourself, you need 
to create one instance of type DefaultMutableTreeNode for every node in your tree. 


Creating a DefaultiMutableTreeNode 
Three constructors are available for creatinginstances of DefaultMutableTreeNode: 
public DefaultMutableTreeNode(>) 


DefaultMutableTreeNode node = new DefaultMutableTreeNode(); 


public DefaultMutableTreeNode(Object userObject) 
DefaultMutableTreeNode node = new DefaultMutableTreeNode("Node"); 


public DefaultMutableTreeNode(Object userObject, boolean allowsChildren) 
DefaultMutableTreeNode node = new DefaultMutableTreeNode("Node", false); 


The information stored at every node is called the user object. When not specified by one 
of the constructors, this user object is null. In addition, you can specify whether a node is 
allowed to have children. 


Building DefaultMutableTreeNode Hierarchies 


Building a hierarchy of nodes of type DefaultMutableTreeNode requires creating an instance 
of type DefaultMutableTreeNode, creating nodes for its children, and then connecting them. 
Before using DefaultMutableTreeNode directly to create the hierarchy, first let's see how to use 
the new NamedVector class to create a tree with four nodes: one root and three leaf nodes. 


Vector vector = new NamedVector("Root", new String[]( "Mercury", "Venus", "Mars") ); 
JTree tree = new JTree(vector); 


662 


CHAPTER 17 TREES 


When JTree gets a Vector as its constructor argument, the tree creates a 
DefaultMutableTreeNode for the root node, and then creates another one for each element in 
the Vector, making each element node a child of the root node. The data for the root node 
unfortunately is not the "Root" you specify, but rather root, and isn't shown. 

Tf, instead, you wanted to use DefaultMutableTreeNode to manually create the nodes ofa 
tree, or ifyou wanted to display the root node, a few more lines would be necessary, as follows: 


DefaultMutableTreeNode root = new DefaultMutableTreeNode("Root"); 
DefaultMutableTreeNode mercury = new DefaultMutableTreeNode("Mercury”); 
root.insert(mercury, 0); 

DefaultMutableTreeNode venus = new DefaultMutableTreeNode("Venus"); 
root.insert(venus, 1); 

DefaultMutableTreeNode mars = new DefaultMutableTreeNode("Mars"); 
root.insert(mars, 2); 

JTree tree = new JTree(root); 


Besides using the insert () method from MutableTreeNode to associate a child with a parent, 
DefaultMutableTreeNode has an add() method that automatically adds a child node at the end, 
without providing an index. 


DefaultMutableTreeNode root = new DefaultMutableTreeNode("Root"); 
DefaultMutableTreeNode mercury = new DefaultMutableTreeNode("Mercury"); 
root .add(mercury); 

DefaultMutableTreeNode venus = new DefaultMutableTreeNode("Venus"); 
root.add(venus); 

DefaultMutableTreeNode mars = new DefaultMutableTreeNode("Mars"); 
root.add(mars); 

JTree tree = new JTree(root); 


Both of the previous blocks of source create a tree like the one shown in Figure 17-17. 
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Figure 17-17. Using DefaultMutableTreeNode 
Ifyou don't need a root node and want the same behavior as if you had used NamedVector 
at the root of a tree, you could do the following, too: 


String elements[] = [ "Mercury", "Venus", "Mars") ; 
JTree tree = new JTree(elements); 
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DefaultMutableTreeNode Properties 


As Table 17-5 shows, there are 22 properties ofDefaultMutableTreeNode. Most ofthe properties 
are read-only, allowing you to find out information about the tree node”s position and relation- 
ships. The user0bject property contains the data specific to the node that was provided to the 
DefaultMutableTreeNode when the node was created. The user0bjectPath property contains an 
array of user objects, from the root (at index 0) to the current node (which could be the root). 


Table 17-5. DefaultMutableTreeNode Properties 


Property Name Data Type Access 

allowsChildren boolean Read-write 
childCount int Read-only 
depth int Read-only 
tirstChild TreeNode Read-only 
tirstLeaf DefaultMutableTreeNode Read-only 
lastChild TreeNode Read-only 
lastLeaf DefaultMutableTreeNode Read-only 
leaf boolean Read-only 
leafCount int Read-only 
level int Read-only 
nextLeaf DefaultMutableTreeNode Read-only 
nextNode DefaultMutableTreeNode Read-only 
nextSibling DefaultMutableTreeNode Read-only 
parent MutableTreeNode Read-write 
path TreeNode[ ] Read-only 
previousLeaf DefaultMutableTreeNode Read-only 
previousNode DefaultMutableTreeNode Read-only 
previousSibling DefaultMutableTreeNode Read-only 
root boolean Read-only 
siblingCount int Read-only 
user0bject Object Read-write 


user0bjectPath Object[ ] Read-only 
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Querying Node Relationships 


The DefaultMutableTreeNode class provides several ways to determine the relationship between 
two nodes. In addition, you can check to see iftwo nodes share a common parent using the 
following methods: 


+ isNodeAncestor(TreeNode aNode): Returns true if aNode is the current node or a parent of 
the current node. This recursively checks getParent () until aNode or null is found. 


+. isNodeChild(TreeNode aNode): Returns true if the current node is the parent of aNode. 


+ isNodeDescendant(DefaultMutableTreeNode aNode): Returns true if the current node is 
aNode or an ancestor of aNode. 


+ isNodeRelated(DefaultMutableTreeNode aNode): Returns true if both the current node 
and aÑode share the same root (are in the same tree). 


+ isNodeSibling(TreeNode aNode): Returns true if both nodes share the same parent. 


Each method returns a boolean value, indicating whether or not the relationship exists. 

Tf two nodes are related, you can ask for the root of the tree to find a shared ancestor. 
However, this ancestor might not be the closest ancestor within the tree. Ifa common 
node exists lower down in the tree, you can use the public TreeNode getSharedAncestor 
(DefaultMutableTreeNode aNode) method to find this closer ancestor. If none exists because 
the two nodes aren't in the same tree, null is returned. 


Note If a node asks for the shared ancestor of that node and itself, the shared ancestor is the node itself. 
In other words, a node”s closest ancestor to itself is itself. 


Traversing Trees 


The TreeNode interface and DefaultMutableTreeNode class provide several means of traveling to 
all the nodes below a specific node. Given a specific TreeNode, you can walk to each descendant 
node by going through the children() ofeach node, including the initial node. Given a specific 
DefaultMutableTreeNode, you can find all the descendants by following both getNextNode() 
and getPreviousNode() methods until no additional nodes are found. The following code frag- 
ment demonstrates the use of the children() method of TreeNode to traverse an entire tree, 
given a starting node. 


public void printDescendants(TreeNode root) ( 
System.out.println(root); 
Enumeration children = root.children(); 
if (children != null) £ 
while(children.hasMoreElements()) ( 
printDescendants((TreeNode)children.nextElement()); 
J 
y 
) 
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Although the DefaultMutableTreeNode implementation of TreeNode allows you to 
traverse a tree via the getNextNode() and getPreviousNode() methods, these methods are 
extremely inefficient and should be avoided. Instead, use one of the special methods of 
DefaultMutableTreeNode to produce one Enumeration of all of a node's children. Before looking 
at the specific methods, review Figure 17-18, which shows a simple tree to traverse. 
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Figure 17-18. Sample tree for traversal 


Figure 17-18 will help you understand the three special methods ofDefaultMutableTreeNode. 
These methods allow you to traverse a tree in any one of three ways, each public and returning 
an Enumeration: 


+ preOrderEnumeration(): Returns an Enumeration of nodes, like the printDescendants() 
method. The first node in the Enumeration is the node itself. The next node is that node's 
first child, then it's the first child of that first child, and so on. Once a leaf node with no 
children is found, the next child ofits parent is putin the Enumeration and its children 
are added to the list accordingly until no nodes are left. Starting at the root for the tree in 
Figure 17-18, this would result in an Enumeration of nodes in the following order: root, 
New York, Mets, Yankees, Rangers, Football, Giants, Jets, Bills, Boston, Red Sox, Celtics, 
Bruins, Denver, Rockies, Avalanche, Broncos. 


+ depthFirstEnumeration() and postOrderEnumeration(): Return an Enumeration that has 
practically the opposite behavior of preOrderEnumeration(). Instead of including the 
current node first and then adding the children, these methods add the children first and 
then add the current node to the Enumeration. For the tree in Figure 17-18, this results in 
an Enumeration of nodes in the following order: Mets, Yankees, Rangers, Giants, Jets, 
Bills, Football, New York, Red Sox, Celtics, Bruins, Boston, Rockies, Avalanche, Broncos, 
Denver, root. 


+ breadthFirstEnumeration(): Returns an Enumeration of nodes added by level. For the 
tree in Figure 17-18, the Enumeration would be in the following order: root, New York, 
Boston, Denver, Mets, Yankees, Rangers, Football, Red Sox, Celtics, Bruins, Rockies, 
Avalanche, Broncos, Giants, Jets, Bills. 
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This leaves but one question: How do you get the starting node? Well, the first node could 
be selected as the result of a user action, or you can ask a tree's TreeModel for its root node. 
You'll explore TreeModel shortly, but the source to get the root node follows. Because TreeNode 
is only one possible type of object that can be stored in a tree, the getRoot() method of TreeModel 
returns an Object. 


TreeModel model = tree.getModel(); 

Object rootObject = model.getRoot(); 

if ((rootObject != null) 3% (root0bject instanceof DefaultMutableTreeNode)) ( 
DefaultMutableTreeNode root = (DefaultMutableTreeNode)root0bject; 


Note | can think of only one reason why you would want to create a replacement to the TreeNode interface 
to describe the basic requirements of a node in a JTree: if you want to use an Iterator from the new Java 
Collections API, instead of an Enumeration to return a list of children, you can create your own replacement 
to TreeNode. This isn't recommended, however. 


JTree.DynamicUtilTreeNode Class 


The JTree class includes an inner class, JTree.DynamicUtilTreeNode, which the tree uses to 
help create the nodes for your trees. The DynamicUtilTreeNode is a DefaultMutableTreeNode 
subclass that doesn't create its child nodes until they're needed. The child nodes are needed 
when you either expand the parent node or try to traverse a tree. Although you normally 
wouldn't use this class directly, you might find a place for it. To demonstrate, the following 
example uses a Hashtable to create the nodes for a tree. Instead of having an invisible node at 
the root ofthe tree (with a user0bject property setting of root), the root node will have a property 
of "Root". 


DefaultMutableTreeNode root = new DefaultMutableTreeNode("Root"); 
Hashtable hashtable = new Hashtable(); 

hashtable.put ("One", args); 

hashtable.put ("Two", new String[ ]("Mercury", "Venus", "Mars")); 
Hashtable innerHashtable = new Hashtable(); 

Properties props = System.getProperties(); 

innerHashtable.put (props, props); 

innerHashtable.put ("Two", new String[ ]("Mercury", "Venus", "Mars")); 
hashtable.put ("Three", innerHashtable); 
JTree.DynamicUtilTreeNode.createChildren(root, hashtable); 

JTree tree = new JTree(root); 


The code just listed creates a tree with the same nodes as shown earlierinthe TreeArraySample 
program in Figure 17-2. However, the nodes at the first level of the tree are in a different order. 
That's because the nodes are in a Hashtable in this example, instead ofin a Vector as in the 
TreeArraySample. The first-level tree elements are added in the order returned by an Enumeration 
of Hashtable, instead of being in the order added to the Vector, as Figure 17-19 shows. 
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Figure 17-19. DynamicUtilTreeNode Hashtable tree sample 


TreeModel Interface 


The TreeModel interface describes the basic data model structure for a JTree. It describes a 
parent-child aggregation relationship, which permits any object to be a parent or a child. There 
is one root to the tree, and all other nodes of the tree are descendants of this node. In addition 
to returning information about the different nodes, the model requires any implementers to 
manage a list of TreeModelListener objects so that the listeners can be notified when any nodes 
in the model have changed. The remaining method, valueForPathChanged(), is meant to provide 
the means of changing the contents of a node at a particular location. 


public interface TreeModel ( 
// Properties 
public Object getRoot(); 
// Listeners 
public void addTreeModellListener(TreeModelListener 1); 
public void removeTreeModellListener(TreeModellistener 1); 
// Instance methods 
public Object getChild(Object parent, int index); 
public int getChildCount(Object parent); 
public int getIndex0fChild(Object parent, Object child); 
public boolean isLeaf(Object node); 
public void valueForPathChanged(TreePath path, Object nenValue); 


DefaultTreeModel Class 


The JTree automatically creates a DefaultTreeModel instance to store its data model. The 
DefaultTreeModel class provides an implementation of the TreeModel interface that uses 
TreeNode implementations at each node. 

In addition to implementing the methods of the TreeModel interface, as well as managing 
a list of TreeModelListener objects, the DefaultTreeModel class adds several helpful methods: 
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+ public void insertNodeInto(MutableTreeNode child, MutableParentNode parent, 
index int): Adds the child node to parent's set of children at the child position index 
(zero-based). 


+ public void removeNodeFromParent(MutableTreenode node): Causes the node to be 
removed from tree. 


+ public void nodeChanged(TreeNode node): Notifies the model that a node has changed. 


+ public void nodesChanged(TreeNode node, int childIndices[]): Notifies the model 
that the child or children of a node have changed. 


+ public void nodeStructureChanged(TreeNode node): Notifies the model ifthe node and 
children have changed. 


+ public void nodesWereInserted(TreeNode node, int childIndices[]): Notifies the 
model that nodes were inserted as children of the tree node. 


+ public void nodesWereRemoved(TreeNode node, int childIndices[], Object 
removedChildren[ ]): Notifies the model that child nodes were removed from the tree 
and includes nodes as arguments in the method call. 


+ public void reload() / public void reload(TreeNode node): Notifies the model that 
there were complex changes made to the nodes and that the model should be reloaded 
from the root node down or from a specific node down. 


The first pair of methods is for directly adding or removing nodes to or from a tree. The 
remaining methods are for notifying the data model when tree nodes are modified. Ifyou don't 
insert or remove nodes into or from the model for a displayed tree with one of the first two 
methods, it's your responsibility to call a method from the second set. 


TreeModelListener Interface and Tree ModelEvent Class 


The TreeModel uses a TreeModelListener to report any changes to the model. When the 
TreeModel sends a TreeModel Event, any registered listeners are notified. The interface includes 
notification methods for when nodes are inserted, removed, or changed, as well as one catchall 
method for when some or all ofthese operations are done simultaneously. 


public interface TreeModellistener implements EventListener ( 
public void treeNodesChanged(TreeModelEvent treeModelEvent); 
public void treeNodesInserted(TreeModelEvent treeModelEvent); 
public void treeNodesRemoved(TreeModelEvent treeModelEvent); 
public void treeStructureChanged(TreeModelEvent treeModelEvent); 
J 


TreeSelectionModel Interface 


In addition to all trees supporting a data model for storing nodes, a renderer for displaying 
nodes, and an editor for editing them, there is a data model called TreeSelectionModel for 
selective manipulation of tree elements. The TreeSelectionModel interface that follows contains 
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methods to describe the selected set of paths to the selected nodes. Each path is stored in a 
TreePath, which itself contains a path of tree nodes from the root object to a selected node. The 
TreePath class will be explored shortly. 


public interface TreeSelectionModel f 
// Constants 


publ 
publ 
publ 


lic final static int CONTIGUOUS TREE SELECTION; 
lic final static int DISCONTIGUOUS TREE SELECTION; 
lic final static int SINGLE _TREE SELECTION; 


// Properties 


publ 
publ 
publ 
publ 
publ 
publ 
publ 
publ 
publ 
publ 
publ 
publ 
publ 
publ 


publ 


ic TreePath getleadSelectionPath(); 

ic int getleadSelectionRow(); 

ic int getMaxSelectionRow(); 

ic int getMinselectionRow(); 

ic RonMapper getRowMapper(); 

ic void setRowMapper(RowMapper newMapper); 
ic int getSelectionCount(); 

ic boolean isSelectionEmpty(); 

ic int getSelectionMode(); 

ic void setSelectionMode(int mode); 

ic TreePath getSelectionPath(); 

ic void setSelectionPath(TreePath path); 
ic TreePath[] getSelectionPaths(); 

ic void setSelectionPaths(TreePath paths[]); 
lic int[] getSelectionRows(); 


// Listeners 


publ 
publ 
publ 
publ 


lic void addPropertyChangeListener(PropertyChangelistener listener); 
lic void removePropertyChangeListener(PropertyChangeListener listener); 
lic void addTreeSelectionListener(TreeSelectionlListener listener); 

lic void removeTreeSelectionListener(TreeSelectionListener listener); 


// Other methods 


publ 
publ 
publ 
publ 
publ 
publ 
publ 
publ 


ic void addSelectionPath(TreePath path); 

ic void addSelectionPaths(TreePath paths[]); 

ic void clearSelection(); 

ic boolean isPathSelected(TreePath path); 

ic boolean isRowSelected(int row); 

ic void removeSelectionPath(TreePath path); 

ic void removeSelectionPaths(TreePath paths[]); 
ic void resetRowSelection(); 


The TreeSelectionModel interface supports three modes of selection, with each mode 
specified by a class constant: CONTIGUOUS TREE_ SELECTION, DISCONTIGUOUS TREE_SELECTION, or 
SINGLE_TREE_SELECTION. When the selection mode is CONTIGUOUS TREE_SELECTION, only nodes 
situated next to each other can be selected simultaneously. The DISCONTIGUOUS TREE_SELECTION 


mode 


means that there are no restrictions on simultaneous selection. With the remaining mode, 


SINGLE_TREE_SELECTION, only one node can be selected at a time. Ifyou don't want anything to be 
selectable, use a setting of null. This uses the protected JTree.EmptySelectionModel class. 
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Note The keys used to select multiple nodes are look-and-feel specific. Try using the Ctrl-select or 
Shift-select keyboard combinations to choose multiple nodes. 


Besides changing selection modes, the remaining methods allow you to monitor attributes of 
the selection path. Sometimes the methods work with row numbers, and other times they work 
with TreePath objects. The selection model uses a RonMapper to map rows to paths for you. The 
abstract AbstractLayoutCache class provides a basic implementation of the RowMapper interface 
that is further specialized by the FixedHeightLayoutCache and VariableHeightLayoutCache 
classes. You should never need to access or modify the RonMapper or any of its implementa- 
tions. To map rows to paths (or paths to rows), just ask a JTree. 


DefaultTreeSelectionModel Class 


The DefaultTreeSelectionModel class provides an implementation of the TreeSelectionModel 
interface that is initially in DISCONTIGUOUS TREE_SELECTION mode and that supports all three 
selection modes. The class introduces some ofits own methods for getting listener lists; the 
other methods are merely implementations of all the TreeSelectionModel interface methods, 
including methods for accessing the 11 properties listed in Table 17-6. In addition, 
DefaultTreeSelectionModel overrides the clone() methods of Object to be Cloneable. 


Table 17-6. DefaultTreeSelectionModel Properties 


Property Name Data Type Access 

leadSelectionPath TreePath Read-only 
leadSelectionRow int Read-only 
maxSelectionRow int Read-only 
minSelectionRow int Read-only 
ronMapper RonMapper Read-write 
selectionCount int Read-only 
selectionEmpty boolean Read-only 
selectionMode int Read-write 
selectionPath TreePath Read-write 
selectionPaths TreePath[] Read-write 
selectionRows int[] Read-only 


The primary reason to use the TreeSelectionModel is to change the selection mode ofthe 
model. For instance, the following two lines of source code change the model to single-selection 
mode: 
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TreeSelectionModel selectionModel = tree.getSelectionModel (>; 
selectionModel.setSelectionMode(TreeSelectionModel.SINGLE TREE SELECTION); 


Il you're interested in finding out the selected path (or paths), you can ask the JTree 
directly. You don't need to get the selected path from the model. 


TreeSelectionListener Interface and TreeSelectionEvent Class 


When the set of selected nodes within a tree changes, a TreeSelectionEvent is generated 
and any registered TreeSelectionListener objects ofthe TreeSelectionModel are notified. 
The TreeSelectionListener can be registered either with the JTree or directly with the 
TreeSelectionModel. The interface definition follows. 


public interface TreeSelectionListener implements EventListener ( 
public void valueChanged(TreeSelectionEvent treeSelectionEvent); 


J 


TreePath Class 


The last major class to examine is TreePath. It has been used in many of the earlier examples in 
this chapter. It describes a read-only collection of nodes that map a path from the root node to 
another node, where the root could be the top of a subtree versus the root of the whole tree. 
Although two constructors exist to create TreePath objects, you'll normally deal with them only 
as the return value from a method. You can also create a new path by adding an element to an 
existing TreePath with public TreePath pathByAddingChild(Object child). 

A TreePath can be thought of as an Object array, in which the first element of the array is 
the root ofthe tree and the last elements called the last path component. In between are all the 
components connecting them. Normally, the elements of the array will be of type TreeNode. 
However, because TreeModel supports objects of any type, the path property of TreePath is 
defined to be an array of Object nodes. Table 17-7 lists the four TreePath properties. 


Table 17-7. TreePath Properties 


Property Name Data Type Access 

lastPathComponent Object Read-only 
parentPath TreePath Read-only 
path Object[ ] Read-only 
pathCount int Read-only 


To better understand TreePath, let's reuse the tree traversal sample tree from Figure 17-18, 
shown once more in Figure 17-20. 
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Figure 17-20. TreePath sample tree 

Using Figure 17-20 to visualize a tree starting from its root, the TreePath for the Jets node 
would be described by its properties as follows: 

. lastPathComponent: A DefaultMutableTreeNode whose user object is Jets. 

+. parentPath: A TreePath made up of the root, New York, and Football nodes. 


+ path: An array of DefaultMutableTreeNode nodes whose user objects are root, New York, 
Football, and Jets. 


* pathCount: 4. 


That's really all there is to the TreePath class. Just remember that you can't change an 
existing TreePath—you can only access its elements. 


Additional Expansion Events 


Two listeners that can be registered with a JTree have yet to be discussed: a 
TreeExpansionListener and a TreeWillExpandListener. 


TreeExpansionListener Interface and TreeExpansionEvent Class 


If you're interested in finding out when a tree node has been expanded or collapsed, you can 
register a TreeExpansionListener with a JTree. Any registered listener will be notified after the 
expansion or collapse of a parent node. 


public interface TreeExpansionListener implements EventListener ( 
public void treeCollapse(TreeExpansionEvent treeExpansionEvent); 
public void treeExpand(TreeExpansionEvent treeExpansionEvent); 


J 
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Each of the methods has a TreeExpansionEvent as its argument. The TreeExpansionEvent 
class has a single method for getting the path to the expanded or collapsed node: public 
TreePath getPath(). 


TreeWillExpandListener Interface and ExpandVetoException 
Class 


The JTree supports the registration of a TreeWillExpandListener, whose definition follows. 


public interface TreeWillExpandListener implements EventListener ( 
public void treeWillCollapse(TreeExpansionEvent treeExpansionEvent) 
throws ExpandVetoException; 
public void treeWillExpand(TreeExpansionEvent treeExpansionEvent) 
throws ExpandVetoException; 


The two method signatures are similar to the TreeExpansionListener, and they can throw 
an ExpandVetoException. Anyregistered listener will be notified prior to the expansion or collapse 
of a parent node. If the listener doesn't want the expansion or collapse to happen, that listener 
can throw the exception to reject the request, stopping the node from opening or closing. 

To demonstrate a TreeWillExpandListener, the following code won't permit either the 
sports node to be expanded in the default data model or the colors node to be collapsed. 


TreeWillExpandListener treeWillExpandListener = new TreeWillExpandListener() ( 
public void treeWillCollapse(TreeExpansionEvent treeExpansionEvent) 
throws ExpandVetoException ( 
TreePath path = treeExpansionEvent.getPath(); 
DefaultMutableTreeNode node = 
(DefaultMutableTreeNode)path.getLastPathComponent(); 
String data = node.getUser0bject().toString(); 
if (data.equals("colors")) ( 
throw new ExpandVetoException(treeExpansionEvent); 
J 
J 
public void treeWillExpand(TreeExpansionEvent treeExpansionEvent) 
throws ExpandVetoException ( 
TreePath path = treeExpansionEvent.getPath(); 
DefaultMutableTreeNode node = 
(DefaultMutableTreeNode)path.getLastPathComponent(); 
String data = node.getUser0bject().toString(); 
if (data.equals("sports")) ( 
throw new ExpandVetoException(treeExpansionEvent); 
y 
J 
A 


Don't forget to add the listener to a tree with a line of code similar to the following: 


tree.addTreeWillExpandListener(treeWillExpandListener) 
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Summary 


In this chapter, you learned about the many classes related to the use of the JTree compo- 
nent. You looked at tree node rendering with the TreeCel1Renderer interface and the 
DefaultTreeCellRenderer implementation. You delved into tree node editing with the 
TreeCellEditor interface, and the DefaultCel1Editor and DefaultTreeCellEditor 
implementations. 

After reviewing how to display and edit a tree, you dealt with the TreeNode interface, 
MutableTreeNode interface, and DefaultMutableTreeNode class for manually creating tree objects. 
You explored the TreeModel interface and DefaultTreeModel implementation for storing the 
data model of a tree, and the TreeSelectionModel interface and DefaultTreeSelectionModel 
implementation for storing the selection model for a tree. 

In addition, you looked at the many event-related classes for the various tree classes, and 
the TreePath for describing node connection paths. 

In Chapter 18, you'll explore the javax.swing.table package and its many classes that can 
be used with the JTable component. 


CHAPTER 18 


Tables 


Chapi: 17 took an in-depth look at the Swing JTree component. In this chapter, you']l 
explore the many details of the JTable component. The component is the standard Swing 
component for displaying two-dimensional data in the form of a grid. 


Introducing Tables 


Figure 18-1 shows a simple example ofa JTable. You'll notice thatitincludes Japanese fonts. In 
order to see the Kanji ideographs in this chapter's sample programs, you will need to have the 
necessary Japanese fonts installed. However, all the examples will work fine without config- 
uring your environment to display Japanese fonts, but instead of seeing the ideographs, you 
will see characters such as question marks or boxes, depending on your platform. 


Note Windows XP Service Pack 2 users will find their systems already have the necessary Japanese fonts 
for the examples in this chapter. If you don't already have them, one place to get these fonts for Windows 
systems is http: //Ftp.monash.edu.au/pub/nihongo/ie31pkja.exe. Solaris users must contact 
Sun to request the Asian outline fonts for Solaris environments. For more information about configuring fonts 
in the Java runtime environment, refer to http: //java.sun.com/j2se/1.5.0/docs/guide/intl/ 
fontconfig.html. 
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Figure 18-1. Sample JTable 


Like the JTree component, the JTable component relies on numerous support classes for its 
inner workings. For the JTable, the support classes are found in the javax.swing.table package. 
The cells within the JTable can be selected by row, column, row and column, or individual cell. 
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It's the responsibility ofthe current ListSelectionModel settings to control the selection within 
a table. 

The display of the different cells within a table is the responsibility ofthe TableCel1Renderer; 
the DefaultCellRenderer offers one such implementation of the TableCellRenderer interface 
in a JLabel subclass. 

Managing the data stored in the cells is accomplished through an implementation of the 
TableModel interface. The AbstractTableModel provides the basics of an implementation ofthe 
interface without any data storage. By comparison, the DefaultTableModel encapsulates the 
TableModel interface and uses a Vector of Vector objects for the data storage. You extend 
AbstractTableModel if you need a different type of storage than the kind supplied by the 
DefaultTableModel, for instance, if you already had the data in your own data structure. 

The TableColumnModel interface and the DefaultTableColumnModel implementation of the 
interface manage the table's data as a series of columns. They work together with the TableColumn 
class to allow for greater flexibility in manipulating individual columns. For example, you can 
store columns of data in the TableModel in an order that's different from the display order within 
the JTable. The TableColumnModel manages a second ListSelectionModel to control table 
column selection. 

At the top of every column is a column header. By default, the TableColumn class relies on 
the JTableHeader class to render a text column header. Nevertheless, you must embed the 
JTable in a scroll pane to see the default header. 

Cells within a JTable can be editable. Ifa cell is editable, how the editingworks depends on 
the TableCellEditor implementation, such as the DefaultCellEditor implementation, which 
extends from AbstractCellEditor. In addition, no classes exist to handle individual rows. Rows 
must be manipulated on a cell-by-cell basis. Behind the scenes, the JTable uses the SizeSequence 
utility class to deal with variable height rows; you won't need to manipulate it yourself. 

There are additional interrelationships among the elements used by the JTable component. 
These relationships will be explored later in this chapter with each specific interface and class. 

To visualize how the JTable elements all fit together, examine Figure 18-2. 
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Figure 18-2. JTable elements 
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JTable Class 


First, let's look at the JTable class, which gives you a way to display data in tabular form 
(see Figures 18-1 and 18-2). 


Creating a JTable 


You have seven different ways to create a JTable. The various constructors allow you to create 
tables from a number of data sources. 


public JTable() 
JTable table = new JTable(); 


public JTable(int rows, int columns) 
JTable table = new JTable(2, 3); 


public JTable(Object rowData[][], Object columnNames[]) 

Object rowData[][] = £ £ "Row1-Column1", "Row1-Column2", "Row1-Column3"), 
£ "Row2-Column1", "Row2-Column2", "Row2-Column3") ); 

Object columnNames[] = £ "Column One", "Column Two", "Column Three"); 

JTable table = new JTable(rowData, columnNames); 


public JTable(Vector rowData, Vector columnNames) 
Vector row0ne = new Vector(); 
row0ne.addElement("Row1-Column1"); 
rowOne.addElement("Row1-Column2"); 
row0ne.addElement("Row1-Column3"); 

Vector rowTwo = new Vector(); 
rowTwo.addElement("Row2-Column1"); 
rowTwo.addElement("Row2-Column2"); 
rowTwo.addElement("Row2-Column3"); 

Vector rowData = new Vector(); 
rowData.addElement(rowOne); 
rowData.addElement(rowTwo); 

Vector columnNames = new Vector(); 

columnNames. addElement ("Column One"); 
columnNames. addElement ("Column Two"); 
columnNames . addElement ("Column Three"); 

JTable table = new JTable(rowData, columnNames); 


public JTable(TableModel model) 
TableModel model = new DefaultTableModel(rowData, columnNames); 
JTable table = new JTable(model); 


public JTable(TableModel model, TableColumnModel columnModel) 
// Swaps column order 

TableColumnModel columnModel = new DefaultTableColumnModel (); 
TableColumn firstColumn = new TableColumn(1); 
firstColumn.setHeaderValue(headers[1]); 
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columnModel . addColumn(FirstColumn); 
TableColumn secondColumn = new TableColumn(o); 
secondColumn.setHeaderValue(headers[0]); 
columnModel . addColumn(secondCo1umn) ; 

JTable table = new JTable(model, columnModel); 


public JTable(TableModel model, TableColumnModel columnModel, 
ListSelectionModel selectionModel) 

// Set single selection mode 

ListSelectionModel selectionModel = new DefaultListSelectionModel/(); 

selectionModel.setSelectionMode(ListSelectionModel.SINGLE SELECTION); 

JTable table = new JTable(model, columnModel, selectionModel); 


The no-argument constructor creates a table with no rows and no columns. The second 
constructor takes two integers to create an empty table with a set number of rows and columns. 


Note Table cells created from JTable constructors are editable, not read-only. To change their contents 
in code, just call the public void setValueAt(Object value, int row, int column) method 
of Table. 


The next two constructors are useful when your tabular data is alreadyin a specially structured 
form. For instance, if your data is already in the form of an array of arrays or a Vector of Vector 
objects, you can create a JTable without creating your own TableModel. A two-row-by-three- 
column table could be created from the array off £ "Row1-Column1", "Row1-Column2", 
"Row1-Column3"), £ "Row2-Column1", "Row2-Column2", "Row2-Column3") j, with another array 
holding the column header names. Similar data structures would be necessary for the vector- 
based constructor. 

The remaining three constructors use JTable-specific data structures. If any one of the 
three arguments is missing, default settings will be used. For example, if you don't specify a 
TableColumnModel, the default implementation DefaultTableColumnModel is used and is auto-filled 
with a display order using the column order of the TableModel. When the selection model 
is missing, the ListSelectionModel will use multiple-selection mode, which means that 
noncontiguous rows, but not columns, can be selected. 


Scrolling JTable Components 


Like other components that may require more space than whats available, the JTable component 
implements the Scrollable interface and should be placed within a JScrol1Pane. Scrollbars 
will appear in a JScroll1Pane when a JTable is too big for the available screen real estate, and 
column header names will appear above each column. Figure 18-3 shows how the table in 
Figure 18-1 would appear if it weren't within a JScrol11Pane. Notice that neither column headers 
nor scrollbars appear. This means you can't determine the meaning of the data, nor can you 
scroll to the undisplayed rows. 
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Figure 18-3. JTable without a JScrollPane 


Therefore, every table you create needs to be placed within a JScrol1Pane by using code 
similar to the following: 


JTable table = new JTable(...); 
JscrollPane scrollPane = new JScrollPane(table); 


Manually Positioning the JTable View 


When a JTable within a JScrollPane is added to a window, the table will automatically appear 
with the table positioned so that the first row and column appear in the upper-left corner. If 
you ever need to return the position to the origin, you can set the viewport position back to 
point (0, 0). 


scrollPane.getViewport().setViewPosition(new Point(0,0)); 


For scrolling purposes, the block increment amount is the visible width and height of the 
viewport, depending on the direction of the scrollbar. The unitincrementis 100 pixels for hori- 
zontal scrolling and the height of a single row for vertical scrolling. See Figure 18-4 for a visual 
representation of these increments. 
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Figure 18-4. JTable scrolling increments 
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Removing Column Headers 


As previously stated, placing a JTable within a JScrol1Pane automatically produces column 
header labels for the different column names. Ifyou don't want column headers, you can 
remove them in one of many different ways. Figure 18-5 shows an example of a table without 
column headers. 


£ Headerless Table -10/ xf 
Row1-Columnt_[Row!?-Column2 [Row!-Column3 
Row2-Column1t [Row2-Colurmn2 [Row2-Column3 


Figure 18-5. JTable without column headers 


The simplest way to remove the column headers is to provide empty strings as the column 
header names. With the third JTable constructor in the previous list of seven constructors, this 
would involve replacing the three column names with "", the empty string. 


Object rowData[][] = (("Row1-Column1", "Row1-Column2", "Row1-Column3"), 
["Row2-Column1", "Row2-Column2", "Row2-Column3")); 

Object columnNames[] = [ "", "", ""); 

JTable table = new JTable(rowData, columnNames); 


JScrollPane scrollPane = new JScrollPane(table); 


Because this method of removing headers also removes the description of the different 
columns, you might want to use another way of hiding column headers. The simplest way is to 
just tell the JTable you don't want table headers: 


table.setTableHeader(nul1); 


You could also remove headers by subclassing JTable and overriding the protected 
configureEnclosingsScrollPane() method, or by telling every TableColumn that its header value 
is empty. These are more complicated ways of performing the same task. 


Note Calling scrol1Pane.setColumnHeaderView(null) doesn't work to clear out the column 
headers. Instead, it causes the JScrol1Pane to use the default column headers. 


JTable Properties 


As Table 18-1 shows, the JTable has many properties, 40 in all. These 40 are in addition to the 
many properties inherited from the JComponent, Container, and Component classes. 


Table 18-1. JTable Properties 
Property Name 
accessibleContext 
autoCreateColumnsFromModel 
autoResizeMode 

cellEditor 
cellSelectionEnabled 
columnCount 

columnModel 
columnSelectionAllowed 
dragEnabled 

editing 

editingColumn 

editingRow 

editorComponent 

gridColor 

intercellSpacing 


model 


preferredScrollableViewportSize 


rowCount 
rowHeight 
rowMargin 


rowSelectionAllowed 


scrollableTracksViemportHeight 
scrollableTracksViemportWidth 


selectedColumn 
selectedColumnCount 
selectedColumns 
selectedRow 
selectedRowCount 
selectedRows 
selectionBackground 
selectionForeground 


selectionMode 


Data Type 


AccessibleContext 
boolean 

int 
TableCellEditor 
boolean 

int 
TableColumnModel 
boolean 


boolean 


boolean 
int 

int 
Component 
Color 
Dimension 
TableModel 
Dimension 
int 

int 

int 
boolean 
boolean 
boolean 
int 

int 

int[ ] 
int 

int 

int[ ] 
Color 
Color 


int 
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Access 
Read-only 


Read-write bound 
Read-write bound 
Read-write bound 
Read-write bound 
Read-only 
Read-write bound 
Read-write bound 
Read-write 
Read-only 
Read-write 
Read-write 
Read-only 
Read-write bound 
Read-write 
Read-write bound 
Read-write 
Read-only 
Read-write bound 
Read-write bound 
Read-write bound 
Read-only 
Read-only 
Read-only 
Read-only 
Read-only 
Read-only 
Read-only 
Read-only 
Read-write bound 
Read-write bound 


Write-only 


TABLES 
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Table 18-1. JTable Properties (Continued) 


Property Name Data Type Access 
selectionModel ListSelectionModel Read-write bound 
showGrid boolean Write-only 
showHorizontalLines boolean Read-write bound 
showVerticallines boolean Read-write bound 
surrendersFocusOnKeystroke boolean Read-write 
tableHeader JTableHeader Read-write bound 
UI TableUI Read-write 
UlClassID String Read-only 


Note Row heights are not fixed. You can change the height of an individual row with public void 
setRowHeight(int row, int rowHeight). 


Most of the JTable properties fitinto one of three categories: display settings, selection 
settings, and auto-resizing settings. 


Display Settings 


The first subset of properties in Table 18-1 allows you to set various display options ofthe JTable. 
In addition to the inherited foreground and background properties from Component, you can change 
the selection foreground (selectionForeground) and background (selectionBackground) colors. 
You also control which (if any) gridlines appear (shonGrid), as well as their color (gridColor). 
The intercellSpacing property setting deals with the extra space within table cells. 


Selection Modes 


You can use any one of three different types of selection modes for a JTable. You can select 
table elements one row at a time, one column at a time, or one cell at a time. These three settings 
are controlled by the rowSelectionAllowed, columnSelectionAllowed, and cellSelectionEnabled 
properties. Initially, only the row selection mode is allowed. Because the default 
ListSelectionModel is in multiselect mode, you can select multiple rows at a time. Ifyou don't 
like multiselect mode, you can change the selectionMode property of the JTable, causing the 
selection mode of the rows and columns of the JTable to change accordingly. Cell selection is 
enabled when both row and column selections are enabled. 

If you're interested in whether any of the rows or columns of the JTable are selected, 
you can inquire with one of the six additional properties of JTable: selectedColumnCount, 
selectedColumn, selectedColumns, selectedRowCount, selectedRow, and selectedRows. 

The ListSelectionModel class provides constants for the different selection modes. The 
ListSelectionModel interface and DefaultListSelectionModel class were both covered with 
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the JList component information in Chapter 13. They're used to describe the current set of 
rows and columns within the JTable component. They have three settings: 


e MULTIPLE INTERVAL_ SELECTION (the default) 
+ SINGLE INTERVAL_SELECTION 
+ SINGLE SELECTION 


The JTable has independent selection models for both rows and columns. The row selection 
model is stored with the selectionModel property ofthe JTable. The column selection model is 
stored with the TableColumnModel. Setting the selectionMode property of a JTable sets the selection 
mode for the two independent selection models of the JTable. 

Once a selection mode has been set and a user interacts with the component, you can ask 
the selection model what happened, or, more precisely, what the user has selected. Table 18-2 
lists the properties available to facilitate selection with the DefaultListSelectionModel. 


Table 18-2. DefaultListSelectionModel Properties 


Property Name Data Type Access 
anchorSelectionIndex int Read-write 
leadAnchorNotificationEnabled boolean Read-write 
leadSelectionIndex int Read-write 
listSelectionListeners ListSelectionListener[ ] Read-only 
axSelectionIndex int Read-only 
inSelectionIndex int Read-only 
selectionEmpty boolean Read-only 
selectionModel int Read-write 
valuelsAdjusting boolean Read-write 


Il you're interested in knowing when a selection event happens, register a 
ListSelectionListener with the ListSelectionModel. The ListSelectionListener was 
demonstrated in Chapter 13 with the JList component. 


Note All table indices are zero-based. So, the first visual column is column 0 internally. 


Auto-Resize Modes 


The last subset of the JTable properties deals with the column-resize behavior of the JTable. 
When the JTable is in a column or window that changes sizes, how does it react? Table 18-3 
shows the five settings supported by a JTable. 


684 CHAPTER 18 TABLES 


Table 18-3. Auto-Resize Mode Constants 


Modes Description 
AUTO_RESIZE_ALL_COLUMNS Adjusts all column widths proportionally. 
AUTO_RESIZE_LAST_COLUMN Adjusts the rightmost column width only to give or 


take space as required by the column currently being 
altered. If no space is available within that column, then 
resizing will work with the previous column until a 
column with available space to consume is found. 


AUTO_RESIZE_NEXT_COLUMN If you're reducing the width of a neighboring column, 
the neighboring column will grow to fill the unused 
space. If you're increasing the width of a column, the 
neighboring column will shrink. 


AUTO_RESIZE_OFF Turns off the user's ability to resize columns. The 
columns can still be resized programmatically. 

AUTO_RESIZE_SUBSEQUENT_COLUMNS Adjusts the width by proportionally altering (default) 
columns displayed to the right of the column being 
changed. 


Listing 18-1 demonstrates what effect each setting has when resizing table columns. 


Listing 18-1. Resizable JTable 


import javax.swing.*; 
import javax.swing.table.*; 
import java.awt.*; 

import java.awt.event.*; 


public class ResizeTable ( 
public static void main(String args[]) ( 


final Object rowData[][] = ( 


("1", "one",  "ichi - MugEe0oo", "un", AE 
["2", "two", "ni - XugE8C", "deux",  "II"), 
("3", "three", "san - MugEo9", "trois", "III"), 
("4", "four", "shi - Mu56DB", "quatre", "IV"), 
(05%, "five", "go - Vu4E94", "cinq",  "V"), 
("6", "six",  "roku - Mu5s16D",  "treiza", "VI"), 
["7", "seven", "shichi - MugE03", "sept",  "VII"), 
("8", "eight", "hachi - 1u5s16B", "huit",  "VIII"), 
["9", "nine", "kyu - AugE5D", "neur", "IX, 
Eo tant O AE A XA 


5 
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final String columnNames[] = ("+", "English", "Japanese", "French", "Roman"y; 


Runnable runner = new Runnable() £ 
public void run() £ 
final JTable table = new JTable(rowData, columnNames); 
JScrollPane scrollPane = new JScrollPane(table); 


String modes[] = ("Resize All Columns", "Resize Last Column", 
"Resize Next Column", "Resize Off", "Resize Subsequent Columns"); 
final int modeKey[] = £ 
JTable.AUTO RESIZE ALL COLUMNS, 
JTable.AUTO RESIZE LAST COLUMN, 
JTable.AUTO RESIZE NEXT_COLUMN, 
JTable.AUTO RESIZE OFF, 
JTable.AUTO RESIZE SUBSEQUENT_ COLUMNS; 
JComboBox resizeModeComboBox = new JComboBox(modes); 
int defaultMode = 4; 
table.setAutoResizeMode(modeKey[defaultMode]); 
resizeModeComboBox.setSelectedIndex(defaultMode) ; 
ItemListener itemListener = new ItemListener() f 
public void itemStateChanged(ItemEvent e) ( 
JComboBox source = (JComboBox)e.getSource(); 
int index = source.getSelectedIndex(); 
table.setAutoResizeMode (modeKey[index]); 


) 
$; 


resizeModeComboBox.addItemListener(itemListener); 


JFrame frame = new JFrame("Resizing Table"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


frame.add(resizeModeComboBox, BorderLayout.NORTH); 
frame.add(scrollPane, BorderLayout.CENTER); 


frame.setSize(300, 150); 
frame.setVisible(true); 
) 
5 
EventQueue.invokeLater(runner); 
y 
) 


Figure 18-6 shows the initial appearance of the program. Change the JComboBox, and you 
change the column resize behavior. 
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* English Japanese French 
12 fone  fichi-= fun 
2 tuvo ni-= deux 
3 three san-= [trois 
4 four Ishi- PB quatre 
5 go- A |cing 


Figure 18-6. Demonstrating JTable resizing column modes 


Rendering Table Cells 


By default, the rendering of table data is done by a JLabel. Whatever value is stored in the table 
is rendered as a text string. The odd thing is that additional default renderers are installed for 
classes such as Date and Number subclasses, but they're not enabled. You'll see how to enable 
these specialized renderers in the “Enabling the Default Table Cell Renderers” section later in 
this chapter. 


Using the TableCellRenderer Interface and DefaultTableCellRenderer Class 


The TableCellRenderer interface defines the single method necessary for that class to be a 
TableCellRenderer. 


public interface TableCellRenderer ( 
public Component getTableCellRendererComponent(JTable table, Object value, 
boolean isSelected, boolean hasFocus, int row, int column); 


— 


By using information given to the getTableCellRendererComponent() method, proper 
renderer components can be created and sent on their way to display the appropriate content 
ofthe JTable. “Proper” means renderers that reflect the table cell state that you”ve decided to 
display, such as when you want to display selected cells differently than unselected cells, or 
how you want the selected cell to appear when it has the input focus. 

To see a simple demonstration of this, look at Figure 18-7, which shows a renderer that 
alternates colors based on which row the renderer is displayed within. 


English Japanese 
UE 


lroku- 


seven Tshichi- 


hachi- 


Figure 18-7. JTable with custom renderer 


The source for the custom renderer used to produce the example in Figure 18-7 is shown 
in Listing 18-2. 
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Listing 18-2. Custom Table Cell Renderer 


import java.awt.*; 
import javax.swing.*; 
import javax.swing.table.*; 


public class EvenOddRenderer implements TableCellRenderer ( 


public static final DefaultTableCellRenderer DEFAULT_RENDERER = 
new DefaultTableCellRenderer(); 


public Component getTableCellRendererComponent(JTable table, Object value, 
boolean isSelected, boolean hasFocus, int row, int column) £ 
Component renderer = 
DEFAULT_RENDERER.getTableCellRendererComponent(table, value, 
isSelected, hasFocus, row, column); 
Color foreground, background; 
if (isSelected) ( 
foreground = Color.YELLOW; 
background = Color.GREEN; 
) else £ 
if (row % 2 == 0) [ 
foreground = Color.BLUE; 
background = Color.WHITE; 
+ else [ 
foreground = Color.WHITE; 
background = Color.BLUE; 
h 
h 


renderer.setForeground(foreground); 
renderer.setBackground (background); 
return renderer; 


TABLES 


Renderers for tables can be installed for individual classes or for specific columns (see the 
“Enabling the Default Table Cell Renderers” section later in this chapter for details). To install 
the renderer as the default renderer for the JTable—in other words, for Object .class—use code 


similar to the following: 


TableCellRenderer renderer = new EvenOddRenderer(); 
table.setDefaultRenderer(Object.class, renderer); 


Once installed, the Even0ddRenderer will be used for any column whose class doesn't have 
a more specific renderer. It's the responsibility ofthe public Class getColumnClass() method 
of TableModel to return the class to be used as the renderer lookup for all the cells in a particular 
column. The DefaultTableMode1 returns Object. class for everything; therefore, Even0OddRenderer 


will be used by all table cells. 
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Note Keep in mind that one renderer component is used for every cell of every column of a particular 
class. No individual renderer is created for each cell. 


The sample program that used the Even0ddRenderer to generate Figure 18-7 is shown in 
Listing 18-3. 


Listing 18-3. Using the Custom Table Cell Renderer 


import javax.swing.*; 
import javax.swing.table.*; 
import java.awt.*; 


public class RendererSample ( 


public static void main(String args[]) ( 
final Object rows[][] = ( 
["one",  "ichi - XuqE00”), 
["two", "ni - XuqE8C"), 
["three", "san - 1uqE09”), 
[("four”, "shi - Xus6DB"), 
["five", "go - Mu4E94"), 
[("six",  "roku - Au516D"p, 
("seven", "shichi - Mu4E03"), 
("eight", "hachi - 1u516B"), 
("nine", "kyu - 1ugqE5D"), 
("ten", "ju - Mu5341") 
5 
final Object headers[] = ("English", "Japanese"); 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("Renderer Sample"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
JTable table = new JTable(rows, headers); 
TableCellRenderer renderer = new EvenOddRenderer(); 
table.setDefaultRenderer(Object.class, renderer); 
JScrollPane scrollPane = new JScrollPane(table); 
frame.add(scrollPane, BorderLayout.CENTER); 
frame.setSize(300, 150); 
frame.setVisible(true); 


) 
5 
EventQueue.invokeLater(runner); 
) 
) 
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Using Tooltips 


By default, your table cell renderers will display any tooltip text you've configured them to 

display. Unlike with the JTree component, you don't need to manually register the table with 
the Too1TipManager. If, however, your table doesn't display tooltip text, the table will respond 
faster if you unregister the table with the Too1TipManager by using code such as the following: 


// Explicitly 
ToolTipManager.sharedInstance().unregisterComponent(aTable); 
// Implicitly 

yourTable.setToo1TipText(null); 


Handling JTable Events 


There are no JTable events that you can register directly with the JTable. To find out when 
something happens, you must register with one ofthe JTable model classes: TableModel, 
TableColumnModel, or ListSelectionModel. 


Customizing a JTable Look and Feel 


Each installable Swing look and feel provides a different JTable appearance and set of default 
UTResource value settings. Figure 18-8 shows the appearance of the JTable component for the 
preinstalled set of look and feel types: Motif, Windows, and Ocean. In all three cases, the third 
row is highlighted, where the coloration shows the first column is being edited. 


(nx 


| English | Japanese 


(0x 


| English Japanese 


Figure 18-8. JTable under different look and feel types 


The available set ofUIResource-related properties for a JTable is shown in Table 18-4. 
The JTable component has 21 different properties. 
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Table 18-4. JTable UlResource Elements 


Property String 


Table. 
Table. 
Table. 
Table. 
Table. 
Table 
Table 
Table 
Table. 
Table. 
Table. 
Table. 
Table. 
Table. 
Table. 
Table. 
Table. 
Table 
Table 
Table. 


actionMap 


ancestorInputMap 


ancestorInputMap.RightToLeft 


background 


darkShadow 


.focusCellBackground 
.focusCellForeground 


.focusCellHighlightBorder 


font 

foreground 

gridColor 

highlight 

light 
rendererUseTableColors 
rendererUseUIBorder 
rowHeight 


scrollPaneBorder 


.selectionBackground 


.selectionForeground 


shadow 


TableUI 


TableModel Interface 


Now that you've looked at the basics ofthe JTable component, you can learn howit internally 
manages its data elements. It does this with the help of classes that implement the TableModel 


interface. 


The TableModel interface defines the framework needed by the JTable to acquire column 
headers and cell values, and modify those cell values when the table is editable. Its definition 


follows: 


Object Type 
ActionMap 
InputMap 
InputMap 
Color 
Color 
Color 
Color 
Border 
Font 
Color 
Color 
Color 
Color 
Boolean 
Boolean 
Integer 
Border 
Color 
Color 
Color 


String 
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public interface TableModel £ 
// Listeners 
public void addTableModelListener(TableModelListener 1); 
public void removeTableModelListener(TableModelListener 1); 
// Properties 
public int getColumnCount(); 
public int getRowCount(); 
// Other methods 
public Class getColumnClass(int columnIndex) |; 
public String getColumnName(int columnIndex) |; 
public Object getValueAt(int rowIndex, int columnIndex); 
public boolean isCellEditable(int rowIndex, int columnIndex); 
public void setValueAt(Object vValue, int rowIndex, int columnIndex); 


AbstractTableModel Class 


The AbstractTableModel class provides the basic implementation of the TableModel interface. 
It manages the TableModellListener list and default implementations for several ofthe TableModel 
methods. When you subclass it, all you need to provide is the actual column and row count, 
and the specific values (getValueAt ()) in the table model. Column names default to labels such 


asA, B,C,..., Z, AA, BB, ..., and the data model is read-only unless isCellEditable() is overridden. 


If you subclass AbstractTableModel and make the data model editable, it's your responsi- 
bility to call one of the following fireXXX() methods of AbstractTableModel to ensure that any 
TableModelListener objects are notified when the data model changes: 


public void fireTableCellUpdated(int row, int column); 

public void fireTableChanged(TableModelEvent e); 

public void fireTableDataChanged(); 

public void fireTableRowsDeleted(int firstRow, int lastRow); 
public void fireTableRowsInserted(int firstRow, int lastRow); 
public void fireTableRowsUpdated(int firstRow, int lastRow); 
public void fireTableStructureChanged(); 


When you want to create a JTable, it's not uncommon to subclass AbstractTableModel in 
order to reuse an existing data structure. This data structure typically comes as the result ofa 
Java Database Connectivity (JDBC) query, but there's no restriction requiring that to be the 
case. To demonstrate, the following anonymous class definition shows how you can treat an 
array as an AbstractTableModel: 


TableModel model = new AbstractTableModel() £ 
Object rowData[][] = £ 
["one",  "ichi"), 
["two",  "ni"), 
["three", "san"), 
["four", "shi"j, 
[("five", "go"), 
["six",  "roku"), 
["seven", "shichi"), 
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("eight", "hachi"), 
("nine", "kyu"), 
("ten",  "ju") 
y; 
Object columnNames[] = (["English", "Japanese"); 
public String getColumnName(int column) £ 
return columnNames[column].toString(); 
) 
public int getRowCount() ( 
return rowData. length; 
) 
public int getColumnCount() ( 
return columnNames. length; 
) 
public Object getValueAt(int row, int col) ( 
return rowData[row][co1]; 
) 
y; 
JTable table = new JTable(model); 
JScrollPane scrollPane = new JScrollPane(table); 


Specifying Fixed JTable Columns 


Now that you've seen the basics of howthe TableModel and AbstractTableModel describe the 
data, you can create a JTable with some columns that are fixed columns and some that are not. 
To create columns that don't scroll, you need to place a second table in the row header view of 
the JScrollPane. Then when the user scrolls the table vertically, the two tables will remain in 
sync. The two tables then need to share their ListSelectionModel. That way, when a rowin one 
table is selected, the row in the other table will automatically be selected. Figure 18-9 shows a 
table with one fixed column and four scrolling columns. 


Fixed Column Scrollable Columns 


42 Fixed Colu=” Tabl<"7 =/0/ xj 
* anese French Roman 
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4 
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4 » 


Figure 18-9. Fixed-column JTable 


The source code used to generate Figure 18-9 is shown in Listing 18-4. 
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Listing 18-4. JTable with Fixed Area 


import javax.swing.*; 
import javax.swing.table.*; 
import java.awt.*; 


public class FixedTable ( 
public static void main(String args[]) ( 


final Object rowData[][] = ( 


(1%, "one",  "ichi", "un", "I", "XugEoo"), 
(M2, "two", "ni", "deux", "II", "uqE8C"), 
("3", "three", "san", "trois", "III", "YugEo9”), 
("4"), "four", "shi", "quatre", "IV", "Mu56DB"), 
(05%), "five", "go", "cinq",  "V", "MugE94"), 
("6"), "six",  "roku",  "treiza", "VI", "Mu5s16D"), 
(07, "seven", "shichi", "sept", "VII", "Xu4E03"), 
("8", "eight", "hachi", "huit", "VIII", "Mu516B"), 
("9", "nine", "kyu", "neur", "IX", "ugE5D"), 
["10", "ten", "ju", "dix", "Xx, "Mu5341") 


3 


final String columnNames[] = 
("+") "English", "Japanese", "French", "Roman", "Kanji"); 


final TableModel fixedColumnModel = new AbstractTableModel() 4 
public int getColumnCount() ( 
return 1; 
) 
public String getColumnName(int column) ( 
return columnNames[ column]; 
) 
public int getRowCount() ( 
return rowData.length; 
J 
public Object getValueAt(int row, int column) ( 
return rowData[row][column]; 
) 
5 


final TableModel mainModel = new AbstractTableModel() 4 
public int getColumnCount() ( 
return columnNames.length-1; 
J 
public String getColumnName(int column) ( 
return columnNames[ column+1] ; 


J 
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public int getRowCount() f 
return rowData.length; 
J 
public Object getValueAt(int row, int column) ( 
return rowData[row][column+1]; 
y 
$»; 


Runnable runner = new Runnable() f 

public void run() ( 
JTable fixedTable = new JTable(fixedColumnModel); 
fixedTable.setAutoResizeMode(JTable.AUTO RESIZE OFF); 


JTable mainTable = new JTable(mainModel); 
ainTable.setAutoResizeMode(JTable.AUTO RESIZE OFF); 


ListSelectionModel model = fixedTable.getSelectionModel (>; 
ainTable.setSelectionModel (model); 


JScrollPane scrollPane = new JScrollPane(mainTable); 
Dimension fixedSize = fixedTable.getPreferredSize(); 
JViewport viewport = new JViemport(); 
viewport.setView(fixedTable); 
viewport.setPreferredSize(fixedSize); 
viewport.setMaximumSize(fixedSize); 
scrollPane.setCorner(JScrollPane.UPPER_LEFT_CORNER, 
fixedTable.getTableHeader()); 
scrollPane.setRowHeaderView(viewport); 


JFrame frame = new JFrame("Fixed Column Table"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
frame.add(scrollPane, BorderLayout.CENTER); 
frame.setSize(300, 150); 
frame.setVisible(true); 
4 
5 
EventQueue.invokeLater(runner); 
J 
) 


Enabling the Default Table Cell Renderers 


Earlier, I mentioned that the JTable provides default renderers for Date and Number classes. 
Let's look at the AbstractTableModel class and see how to enable those renderers. 
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The public Class getColumnClass(int column) method ofthe TableModel returns the class 
type for a column in the data model. Ifthe JTable class has a special renderer installed for that 
particular class, it will use it to display that class. By default, the AbstractTableModel (and 
DefaultTableModel) implementations of TableModel return Object.class for everything. The 
AbstractTableModel class doesn't try to be smart about guessing what's in a column. However, 
ifyou know that a particular column of the data model will always be numbers, dates, or some 
other class, you can have the data model return that class type. This allows the JTable to try to 
be smarter and use a better renderer. 

Table 18-5 shows the preinstalled renderers within the JTable. Ifyou have a table full of 
numbers or just one column of numbers, for example, you can override getColumnClass() to 
return Number. class for the appropriate columns; your numbers will be right-justified instead 
of left-justified. With dates, using the default renderer for the Date class produces better-looking, 
localized output. 


Table 18-5. Default JTable Renderers 


Class Renderer Description 

Boolean JCheckBox Centered 

Date JLabel Right-aligned; uses DateFormat for output 
Double JLabel Right-aligned; uses NumberFormat for output 
Float JLabel Right-aligned; uses NumberFormat for output 
Icon JLabel Centered 

Imagelcon JLabel Centered 

Number JLabel Right-aligned 

Object JLabel Left-aligned 


Figure 18-10 shows how a table might look before and after enabling the renderers. 
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Figure 18-10. Before and after enabling the renderers 


You can choose to hard-code the class names for columns or have the getColumnClass() 
method be generic and just call getClass() on an element in the column. Adding the following 
codeto an AbstractTableModel implementation would allowthe JTable to use its defaultrenderers. 
This implementation assumes that all entries for a particular column are one class type. 
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public Class getColumnClass(int column) ( 
return (getValueAt(O0, column) .getClass()); 


J 


DefaultTableModel Class 


The DefaultTableModel is a subclass of AbstractTableModel that provides its own Vector data 
structure for storage. Everything in the data model is stored within vectors internally, even 
when the data is initially part of an array. In other words, if you already have your data in an 
adequate data structure, don't use DefaultTableModel. Create an AbstractTableModel that uses 
the structure, instead of having a DefaultTableModel convert the structure for you. 


Creating a DefaultTableModel 


There are six constructors for DefaultTableModel: 


public DefaultTableModel() 
TableModel model = new DefaultTableModel () 


public DefaultTableModel(int rows, int columns) 
TableModel model = new DefaultTableModel(2, 3) 


public DefaultTableModel(Object rowData[][], Object columnNames][]) 

Object rowData[][] = (("Row1-Column1", "Row1-Column2", "Row1-Column3"), 
["Row2-Column1", "Row2-Column2", "Row2-Column3")); 

Object columnNames[] = ["Column One", "Column Two", "Column Three"); 

TableModel model = new DefaultTableModel(rowData, columnNames); 


public DefaultTableModel(Vector rowData, Vector columnNames) 
Vector row0ne = new Vector(); 
row0ne.addElement("Row1-Column1"); 
row0ne.addElement("Row1-Column2"); 
row0ne.addElement("Row1-Column3"); 

Vector rowTwo = new Vector(); 
rowTwo.addElement("Row2-Column1"); 
rowTwo.addElement("Row2-Column2"); 

rowTwo.addElement ("Row2-Column3"); 

Vector ronData = new Vector(); 

rowData.addElement(rowOne) ; 

rowData.addElement(rowTwo) ; 

Vector columnNames = new Vector(); 
columnNames . addElement ("Column One"); 
columnNames . addElement ("Column Two"); 
columnNames . addElement ("Column Three"); 

TableModel model = new DefaultTableModel(rowData, columnNames); 
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public DefaultTableModel(Object columnNames[], int rows) 
TableModel model = new DefaultTableModel(columnNames, 2); 


public DefaultTableModel(Vector columnNames, int rows) 
TableModel model = new DefaultTableModel(columnNames, 2); 


Four of the constructors map directly to JTable constructors, whereas the remaining two 
allow you to create empty tables from a set of column headers with a fixed number of rows. 
Once you've created the DefaultTableModel, you pass it along to a JTable constructor to create 
the actual table, and then place the table in a JScrol1Pane. 


Filling a DefaultTableModel 


If you choose to use a DefaultTableModel, you must fill it with data for your JTable to display 
anything. Along with basic routines to fill the data structure, there are additional methods to 
remove data or replace the entire contents: 

The following methods allow you to add columns: 


public void addColumn(Object columnName) |; 
public void addColumn(Object columnName, Vector columnData); 
public void addColumn(Object columnName, Object columnData[ ]); 


Use these methods to add rows: 


public void addRow(Object rowData[ ]); 
public void addRow(Vector rowData); 


These methods insert rows: 


public void insertRow(int row, Object rowData[ ]); 
public void insertRow(int row, Vector rowData); 


This method removes rows: 
public void removeRow( int row); 

And finally, you can replace contents with the following two methods: 
public void setDataVector(Object newData[ ][ ], Object columnNames[ ]); 


public void setDataVector(Vector newData, Vector columnNames); 


DefaultTableModel Properties 


In addition to the rowCount and columnCount properties inherited from AbstractTableModel, 
DefaultTableModel has two other properties, as shown in Table 18-6. Setting the rowCount 
property allows you to enlarge or shrink the table size as you please. Ifyou are expanding the 
model, the additional rows remain empty. 
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Table 18-6. DefaultTableModel Properties 


Property Name Data Type Access 

columnCount int Read-only 
columnTdentifiers Vector Write-only 
dataVector Vector Read-only 
rowCount int Read-write 


Creating a Sparse Table Model 


The default table model implementations are meant for tables that are full of data, not for 
spreadsheets consisting of mostly empty cells. When the cells in the table are mostly empty, 
the default data structure for the DefaultTableModel will end up with plenty of wasted space. 
At the cost of creating a Point for each lookup, you can create a sparse table model that can use 
a HashMap underneath it. Listing 18-5 demonstrates one such implementation. 


Listing 18-5. Sparsely Populated Table Model 


import java.awt.Point; 

import java.util.HashMap; 

import java.util.Map; 

import javax.swing.table.AbstractTableModel; 


public class SparseTableModel extends AbstractTableModel ( 
static final long serialVersionUID = 5774430402629969511L; 


private Map<Point, Object> lookup; 
private final int rows; 

private final int columns; 
private final String headers[]; 


public SparseTableModel(int rows, String columnHeaders[]) £ 
if ((rows < 0) || (columnHeaders == null)) ( 
throw new IllegalArgumentException("Invalid row count/columnHeaders"); 
J 
this.rows = rows; 
this.columns = columnHeaders. length; 
headers = columnHeaders; 
lookup = new HashMap<Point, Object>(); 
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public int getColumnCount() ( 
return columns; 


J 


public int getRowCount() ( 
return rows; 


J 


public String getColumnName(int column) ( 
return headers[ column]; 


J 


public Object getValueAt(int row, int column) £ 
return lookup.get(new Point(row, column)); 


J 


public void setValueAt(Object value, int row, int column) ( 
if ((rows < 0) || (columns < 0)) 4 
throw new IllegalArgumentException("Invalid row/column setting"); 
) 
if ((row < rows) 88 (column < columns)) 4 
lookup.put(new Point(row, column), value); 
, 
) 
) 


Testing this example involves creating and filling up the model, as follows: 


String headers[] = £ "English", "Japanese"); 
TableModel model = new SparseTableModel(10, headers); 
JTable table = new JTable(model); 
model.setValueAt("one", 0, 0); 
model.setValueAt("ten", 9, 0); 

model.setValueAt("roku - Y u516D", 5, 1); 
model.setValueAt("hachi - Y u516B", 8, 1); 


Listening to JTable Events with a TableModelListener 


If you want to dynamically update your table data, you can work with a TableModelListener to 
find out when the data changes. The interface consists of one method that tells you when the 
table data changes. 


public interface TableModellistener extends EventListener ( 
public void tableChanged(TableModelEvent e); 


, 


After the TableModelListener is notified, you can ask the TableModelEvent for the type of 
event that happened and the range of rows and columns affected. Table 18-7 shows the prop- 
erties of the TableModelEvent you can inquire about. 
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Table 18-7. TableModelEvent Properties 


Property Name Data Type Access 

column int Read-only 
FirstRow int Read-only 
lastRow int Read-only 
type int Read-only 


The event type can be one of three type constants of TableModelEvent: INSERT, UPDATE, 
or DELETE. 

Ifthe column property setting for the TableModelEvent is ALL_COLUMNS, then all the columns 
in the data model are affected. Ifthe firstRow property is HEADER_RONW, it means the table header 
changed. 


Sorting JTable Elements 


The JTable component doesn't come with built-in support for sorting. Nevertheless, this 
feature is frequently requested. Sorting doesn't require changing the data model, but it does 
require changing the view of the data model that the JTable has. This type of change is described 
by the Decorator pattern, in which you maintain the same API to the data but add sorting capa- 
bilities to the view. The participants of the Decorator design pattern are as follows: 


+ Component: The component defines the service interface that will be decorated. 
+ ConcreteComponent: The concrete component is the object to be decorated. 


+ Decorator: The decorator is an abstract wrapper to a concrete component; it maintains 
the service interface. 


+ ConcreteDecorator(s) [A, B, C,....]: The concrete decorator objects extend the decorator 
by adding decorating responsibilities while maintaining the same programming interface. 
They redirect service requests to the concrete component referred to by their abstract 
superclass. 


Note The streams of the java.io package are examples of the Decorator pattern. The various filter 
streams add capabilities to the basic stream classes and maintain the same API for access. 


In the particular case for table sorting, only the Component, ConcreteComponent, and 
Decorator are required, because there is only one concrete decorator. The Component is the 
TableModel interface, the ConcreteComponent is the actual model, and the Decorator is the 
sorted model. 
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In order to sort, you need to maintain a mapping of the real data to the sorted data. From 
the user interface, you must allow the user to select a column header label to enable sorting of 
a particular column. 

To use the sorting capabilities, you tell the custom TableSorter class about your data 
model, decorate it, and create a JTable from your decorated model instead of the original. To 
enable the sorting by picking column header labels, you need to call the custom install () 
method of the TableHeaderSorter class shown in the following source code for the TableSorter 
class: 


TableSorter sorter = new TableSorter(model); 
JTable table = new JTable(sorter); 
TableHeadersorter.install(sorter, table); 


The main source code for the TableSorter class is shown in Listing 18-6. It extends from 
the TableMap class, which is shown in Listing 18-7. The TableSorter class is where all the action 
is. The class does the sorting and notifies others that the data has changed. 


Listing 18-6. Table Column Sorting 


import javax.swing.*; 
import javax.swing.table.*; 
import javax.swing.event.*; 
import java.awt.event.*; 
import java.util.*; 


public class TableSorter extends TableMap implements TableModelListener f 
int indexes[] = new int[o0]; 
Vector sortingColumns = new Vector(); 
boolean ascending = true; 


public TableSorter() ( 
) 


public TableSorter(TableModel model) f 
setModel (model); 
) 


public void setModel(TableModel model) ( 
super.setModel (model); 
reallocatelndexes(); 
sortByColumn(0) ; 
fireTableDataChanged(); 

) 


public int compareRowsByColumn(int row1, int row2, int column) £ 
Class type = model .getColumnClass (column); 
TableModel data = model; 
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// Check for nulls 


Object 01 = data.getValueAt (row1, column); 
Object 02 = data.getValueAt (row2, column); 


// TF both values are null return O 
if (01 == null 88 02 == null) € 


return 0; 

) else if (01 == null) £ // Define null less than everything. 
return -1; 

Y else if (02 == null) ( 
return 1; 


J 


if (type.getSuperclass() == Number.class) ( 
Number n1 = (Number)data.getValueAt(row1, column); 
double d1 = n1.doubleValue(); 
Number n2 = (Number)data.getValueAt(row2, column); 
double d2 = n2.doubleValue(); 


if (d1 < d2) 
return -1; 
else if (d1 > d2) 
return 1; 
else 
return 0; 
) else if (type == String.class) ( 
String s1 = (String)data.getValueAt(row1, column); 
String s2 = (String)data.getValueAt(row2, column); 
int result = s1.compareTo(s2); 


if (result < 0) 
return -1; 
else if (result > 0) 
return 1; 
else 
return 0; 
) else if (type == java.util.Date.class) ( 


Date d1 = (Date)data.getValueAt(row1, column); 
long n1 = d1.getTime(); 
Date d2 = (Date)data.getValueAt(row2, column); 
long n2 = d2.getTime(); 
if (n1 < n2) 

return -1; 


else if (n1 > n2) 
return 1; 
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else 
return 0; 
$ else if (type == Boolean.class) f 
Boolean boo11 = (Boolean)data.getValueAt(row1, column); 
boolean b1 = boo11.booleanValue(); 
Boolean boo12 = (Boolean)data.getValueAt(row2, column); 
boolean b2 = boo12.booleanValue(); 


if (b1 == b2) 
return 0; 
else if (b1) // Define false < true 
return 1; 
else 
return -1; 
) else f 


Object v1 = data.getValueAt(row1, column); 
String s1 = v1.toString(); 

Object v2 = data.getValueAt(row2, column); 
String s2 = v2.toString(); 

int result = s1.compareTo(s2); 


if (result < 0) 
return -1; 
else if (result > 0) 
return 1; 
else 
return 0; 
) 
) 
public int compare(int row1, int row2) ( 
for (int level=0, n=sortingColumns.size(); level < n; level++) ( 
Integer column = (Integer)sortingColumns.elementAt (level); 
int result = compareRowsByColumn(row1, row2, column.intValue()); 
if (result != 0) £ 
return (ascending ? result : -result); 
) 
) 


return 0; 


J 


public void reallocatelndexes() ( 
int rowCount = model.getRowCount(); 
indexes = new int[rowCount]'; 
for (int row = 0; row < rowCount; row++) ( 
indexes[row] = row; 
) 
) 
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public void tableChanged(TableModelEvent tableModelEvent) ( 
super .tableChanged(tableModelEvent); 
reallocatelndexes(); 
sortByColumn(0); 
fireTableStructureChanged(); 


J 


public void checkModel() € 
if (indexes.length != model.getRowCount()) ( 
System.err.println("Sorter not informed of a change in model."); 
J 
J 


public void sort() ( 
checkModel(); 
shuttlesort((int[])indexes.clone(), indexes, 0, indexes.length); 
fireTableDataChanged(); 


J 


public void shuttlesort(int from[], int to[], int low, int high) ( 
if (high - low< 2) ( 
return; 
) 
int middle = (low + high)/2; 
shuttlesort(to, from, low, middle); 
shuttlesort(to, from, middle, high); 


int p = low; 
int q = middle; 


for (int i = low; i< high; i++) ( 
if (q >= high || (p < middle 88 compare(from[p], from[q]) <= 0)) 4 
to[i] = from[p++]; 
y else f 
to[i] = from[q++]; 
) 
) 
) 


private void swap(int first, int second) ( 


int temp = indexes[first]; 
indexes[first] = indexes[second]; 
indexes[second] = temp; 


) 
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public Object getValueAt(int row, int column) ( 
checkModel () ; 
return model.getValueAt(indexes[row], column); 


. 


public void setValueAt(Object aValue, int row, int column) ( 
checkModel () ; 
model .setValueAt(aValue, indexes[row], column); 


h 


public void sortByColumn(int column) £ 
sortByColumn(column, true); 


J 


public void sortByColumn(int column, boolean ascending) f 
this.ascending = ascending; 
sortingColumns.removeA11Elements(); 
sortingColumns.addElement (new Integer(column)); 
sort(); 
super.tableChanged(new TableModelEvent(this)); 


Note The TableSorter borrows heavily from the Ta bleExample that comes with the JFC/Swing release. 


The TableMap class, shown in Listing 18-7, serves as a proxy, passing along all calls to the 
appropriate TableModel class. It's the superclass of the TableSorter class shown in Listing 18-6. 


Listing 18-7. Table Sorting Support Map 


import javax.swing.table.*; 
import javax.swing.event.*; 


public class TableMap extends AbstractTableModel implements TableModelListener £ 
TableModel model; 
public TableModel getModel() ( 


return model; 


J 
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public void setModel(TableModel model) ( 
if (this.model != null) £ 
this.model.removeTableModelListener(this); 
J 
this.model = model; 
if (this.model != null) ( 
this.model.addTableModelListener(this); 
J 
J 


public Class getColumnClass(int column) ( 
return model.getColumnClass (column) ; 


J 


public int getColumnCount() ( 
return ((model == null) ? O : model.getColumnCount()); 
) 


public String getColumnName(int column) £ 
return model. getColumnName (column); 


J 


public int getRowCount() ( 
return ((model == null) ? O : model.getRowCount()); 
) 


public Object getValueAt(int row, int column) £ 
return model.getValueAt(row, column); 


J 


public void setValueAt(Object value, int row, int column) € 
model.setValueAt(value, row, column); 


J 


public boolean isCellEditable(int row, int column) € 
return model.isCellEditable(row, column); 


J 


public void tableChanged(TableModelEvent tableModelEvent) ( 
fireTableChanged(tableModelEvent); 
J 
) 


Installation of the sorting routines requires the registration of a MouseListener, as shown 
in Listing 18-8, so that selection within the table header triggers the sorting process. Regular 
mouse clicks are ascending sorts; Shift-clicks are descending sorts. 
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Listing 18-8. Mouse Listener for Table Sorting 


import javax.swing.*; 
import javax.swing.table.*; 
import javax.swing.event.*; 
import java.awt.event.*; 
import java.util.*; 


public class TableHeaderSorter extends MouseAdapter ( 


private TableSorter sorter; 
private JTable table; 


private TableHeaderSorter() ( 
i 


public static void install(TableSorter sorter, JTable table) ( 
TableHeaderSorter tableHeaderSorter = new TableHeaderSorter(); 
tableHeaderSorter.sorter = sorter; 
tableHeaderSorter.table = table; 
JTableHeader tableHeader = table.getTableHeader(); 
tableHeader.addMouseListener(tableHeaderSorter); 


J 


public void mouseClicked(MouseEvent mouseEvent) ( 
TableColumnModel columnModel = table.getColumnModel (>); 
int viewColumn = columnModel.getColumnIndexAtX(mouseEvent.getX()); 
int column = table.convertColumnIndexToModel (viewColumn); 
if (mouseEvent.getClickCount() == 1 88 column != -1) ( 
System.out.println("Sorting ..."); 
int shiftPressed = (mouseEvent.getModifiers() 8 InputEvent.SHIFT_MASK); 
boolean ascending = (shiftPressed == 0); 
sorter.sortByColumn(column, ascending); 
) 
) 
) 


Note Chapter 19 includes a demonstration using the TableSorter to sort a table of system properties. 


TableColumnModel Interface 


TableColumnModel is one of those interfaces that lives in the background and usually doesn't 
require much attention. It basically manages the set of columns currently being displayed by a 
JTable. Unless triggered to do otherwise, when a JTable is created, the component builds a 
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default column model from the data model, specifying that the display column order remains 
in the data model order. 

When the autoCreateColumnsFromModel property of JTable is set (true) prior to setting the 
data model of the JTable, the TableColumnModel is automatically created. In addition, you can 
manually tell the JTable to create the default TableColumnModel if the current settings need to 
be reset. The public void createDefaultColumnsFromModel () method does the creation for 
you, assigning the new creation to the TableColumnModel of the JTable. 

With all that automatically done for you, why do you need to look at the TableColumnModel? 
Usually, you'll need to work with this interface only when you don't like the defaults or when 
you want to manually move things around. In addition to maintaining a set of TableColumn 
objects, the TableColumnModel manages a second ListSelectionModel, which allows users to 
select columns and rows from the table. 

Let's take a look at the interface definition before getting into the default implementation. 


public interface TableColumnModel £ 
// Listeners 
public void addColumnModelListener(TableColumnModelListener 1); 
public void removeColumnModelListener(TableColumnModelListener 1); 
// Properties 
public int getColumnCount (); 
public int getColumnMargin(); 
public void setColumnMargin(int newMargin); 
public Enumeration getColumns(); 
public boolean getColumnSelectionAllowea(); 
public void setColumnSelectionAllowed(boolean flag); 
public int getSelectedColumnCount (); 
public int[ ] getSelectedColumns(); 
public ListSelectionModel getSelectionModel (>); 
public void setSelectionModel (ListSelectionModel newModel); 
public int getTotalColumnwWidth(); 
// Other methods 
public void addColumn(TableColumn aColumn); 
public TableColumn getColumn(int columnIndex); 
public int getColumnIndex(Object columnIdentifier); 
public int getColumnIndexAtX(int xPosition); 
public void moveColumn(int columnIndex, int newIndex); 
public void removeColumn(TableColumn column); 


DefaultTableColumnModel Class 


The DefaultTableColumnModel class defines the implementation ofthe TableColumnModel inter- 
face used by the system. It describes the general appearance of the TableColumn objects within 
the JTable by tracking margins, width, selection, and quantity. Table 18-8 shows the nine 
properties for accessing the DefaultTableColumnModel settings. 
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Table 18-8. DefaultTableColumnModel Properties 


Property Name Data Type Access 

columnCount int Read-only 
columnMargin int Read-write 
columnModellisteners TableColumnModelListener[ ] Read-only 
columns Enumeration Read-only 
columnSelectionAllowed boolean Read-write 
selectedColumnCount int Read-only 
selectedColumns int[ ] Read-only 
selectionModel ListSelectionModel Read-write 
totalColumnwWidth int Read-only 


In addition to the class properties, you can use the following methods to add, remove, and 
move columns through the TableColumn class, which will be discussed shortly. 


public void addColumn(TableColumn newColumn); 
public void removeColumn(TableColumn oldColumn); 
public void moveColumn(int currentIndex, int newIndex); 


Listening to JTable Events with a TableColumnModelListener 


One of the things you might want to do with a TableColumnModel is listen for 
TableColumnModelEvent objects with a TableColumnModelListener. The listener will be notified 
of any addition, removal, movement, or selection of columns, or changing of column margins, 
as shown by the listener interface definition. Note that the different methods don't all receive 
TableColumnModelEvent objects when the event happens. 


public interface TableColumnModelListener extends EventListener ( 
public void columnAdded(TableColumnModelEvent e); 
public void columnMarginChanged(ChangeEvent e); 
public void columnMoved(TableColumnModelEvent e); 
public void columnRemoved(TableColumnModelEvent e); 
public void columnSelectionChanged(ListSelectionEvent e); 


Because the listener definition identifies the event type, the TableColumnModel Event definition 
defines only the range of columns affected by the change, as shown in Table 18-9. 


Table 18-9. TableColumnModelEvent Properties 
Property Name Data Type Access 


fromIndex int Read-only 


toIndex int Read-only 
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To see a demonstration of the TableColumnModelListener, you can attach a listener to one 
of your TableColumnModel objects: 


TableColumnModel columnModel = table.getColumnModel (>); 
columnModel . addColumnModelListener(...); 


One such listener is shown in Listing 18-9. It doesn't do much besides print a message. 
Nevertheless, you can use it to see when different events happen. 


Listing 18-9. Table Column Model Listener 


TableColumnModelListener tableColumnModelListener = 
new TableColumnModelListener() f 
public void columnAdded(TableColumnModelEvent e) f 
System.out.println("Added"); 
) 
public void columnMarginChanged(ChangeEvent e) ( 
System.out.println("Margin"); 
) 
public void columnMoved(TableColumnModelEvent e) f 
System.out.println("Moved"); 
) 
public void columnRemoved(TableColumnModelEvent e) ( 
System.out.println("Removed"); 
) 
public void columnSelectionChanged(ListSelectionEvent e) ( 
System.out.println("Selected"); 
) 
$»; 


Of course, you do need to create some code to elicit certain events. Forinstance, margins don't 
appear out of thin air. But you can add the same column multiple times to add more columns (or 
remove them). The program shown in Listing 18-10 tests the new TableColumnModellListener. 


Listing 18-10. Playing with Table Columns 


import javax.swing.event.*; 
import javax.swing.table.*; 
import javax.swing.*; 
import java.awt.*; 


public class ColumnModelSample ( 
public static void main(String args[]) ( 
final Object rows[][] = € 
["one",  "ichi - XugE00"), 
[("two", "ni - 1u4E8C"P, 
["three", "san - 1ugE09"), 
[("four", "shi - 1u56DB"P, 
("five", "go - Mu4E94"), 


$; 
fi 
Ru 


E; 


CHAPTER 18 


("six",  "roku - Mus16D"?, 
("seven", "shichi - 1ugE03"), 
("eight", "hachi - Xu516B"), 
("nine", "kyu - 1ugE5D"), 
["ten", — "ju - Vus341") 


nal Object headers[] = ("English", "Japanese"); 

nnable runner = new Runnable() 4 

public void run() £ 
JFrame frame = new JFrame("Scrollless Table"); 
frame.setDefaultClose0peration(JFrame.EXIT_ON CLOSE); 
JTable table = new JTable(rows, headers); 


TableColumnModelListener tableColumnModelListener = 
new TableColumnModelListener() £ 
public void columnAdded(TableColumnModelEvent e) £ 
System.out.println("Added"); 
) 
public void columnMarginChanged(ChangeEvent e) ( 
System.out.println("Margin"); 
) 
public void columnMoved(TableColumnModelEvent e) £ 
System.out.println("Moved"); 
) 
public void columnRemoved(TableColumnModelEvent e) f 
System.out.println("Removed"); 
) 
public void columnSelectionChanged(ListSelectionEvent e) ( 
System.out.println("Selection Changed"); 
) 
$; 


TableColumnModel columnModel = table.getColumnModel (>); 
columnModel . addColumnModelListener(tableColumnModelListener); 


columnModel. setColumnMargin(12); 


TableColumn column = new TableColum(1); 
columnModel . addColumn(column); 


JScrollPane pane = new JScrollPane(table); 
frame.add(pane, BorderLayout.CENTER); 
frame.setSize(300, 150); 
frame.setVisible(true); 
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EventQueue.invokeLater(runner); 
) 
de 


TableColumn Class 


TableColumn is another important class that lives behind the scenes. Swing tables consist of 

a group of columns, which are made up of cells. Each of those columns is described by a 
TableColumn instance. Each instance of the TableColumn class stores the appropriate editor, 
renderer, name, and sizing information. TableColumn objects are then grouped together into a 
TableColumnModel to make up the current set of columns to be displayed by a JTable. One useful 
trick to remember is if you don't want a column to be displayed, remove its TableColumn from 
the TableColumnModel but leave itin the TableModel. 


Creating a TableColumn 


Ifyou choose to create your TableColumn objects yourself, you can use any one of four constructors. 
They cascade by adding more constructor arguments. 


public TableColumn() 
TableColumn column = new TableColumn() 


public TableColumn(int modelIndex) 
TableColumn column = new TableColumn(2) 


public TableColumn(int modelIndex, int width) 
TableColumn column = new TableColumn(2, 25) 


public TableColumn(int modelIndex, int width, TableCellRenderer 
renderer, TableCellEditor editor) 
TableColumn column = new TableColumn(2, 25, aRenderer, aEditor) 


Note All column settings start at zero. Therefore, new TableColumn(2) uses column 3 from the 
TableModel. 


With no arguments, such as in the first constructor in this list, you get an empty column 
with a default width (75 pixels), a default editor, and a default renderer. The model Index argu- 
ment allows you to specify which column from the TableModel you would like the TableColumn 
to display within the JTable. You can also specify a width, a renderer, or an editor if you don't 
like the defaults. If you like one default but not the other, you can also specify null for the 
renderer or editor. 
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TableColumn Properties 


Table 18-10 lists the 12 properties ofthe TableColumn. These properties allow you to customize a 
column beyond the initial set of constructor arguments. Most of the time, everything is config- 
ured for you based on the TableModel. However, you can still customize individual columns 
through the TableColumn class. Yes, all the properties are bound, except for the listener list. 


Note Ifan identifier isn't specified, the headerValue setting is used instead. 


Table 18-10. TableColumn Properties 


Property Name Data Type Access 
cellEditor TableCellEditor Read-write bound 
cellRenderer TableCellRenderer Read-write bound 
headerRenderer TableCellRenderer Read-write bound 
headerValue Object Read-write bound 
identifier Object Read-write bound 
maxWidth int Read-write bound 
minWidth int Read-write bound 
model Index int Read-write bound 
preferredWidth int Read-write bound 
propertyChangeListeners PropertyChangeListener[ ] Read-only 
resizable boolean Read-write bound 
width int Read-write bound 


Caution If headerRenderer ¡is null, the default header renderer is used by the column: 
TableCellRenderer headerRenderer = table.getTableHeader().getDefaultRenderer();. 
The default is not returned by the getHeaderRenderer() method. 


Using Icons in Column Headers 


By default, the header renderer for a table displays text or HTML. Although you can get multiple 
lines of text and images with HTML, there may come a time when you want to display regular 
Icon objects within a header, as shown in the example in Figure 18-11. To do this, you must 
change the header's renderer. The header renderer is just another TableCellRenderer. 
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Figure 18-11. Icons in table headers 


To create a flexible renderer that can display icons, have the renderer treat the value data 
asa JLabel, instead of using the value to fill the JLabel (or for that, matter any JComponent). 
Listing 18-11 shows one such renderer, which is used in the program that created Figure 18-11. 


Listing 18-11. Custom Table Cell Renderer for [Components 


import java.awt.*; 
import javax.swing.*; 
import javax.swing.table.*; 


public class JComponentTableCellRenderer implements TableCellRenderer ( 
public Component getTableCellRendererComponent(JTable table, Object value, 
boolean isSelected, boolean hasFocus, int row, int column) f 
return (JComponent)value; 
de 
y 


Figure 18-11 shows how this renderer might appear with the DiamondIcon as the Icon. The 
source for the sample program is shown in Listing 18-12. 


Listing 18-12. Customizing Column Headers with Icons 


import javax.swing.*; 
import javax.swing.border.*; 
import javax.swing.table.*; 
import java.awt.*; 


public class LabelHeaderSample ( 
public static void main(String args[]) ( 
final Object rows[][] = ( 

["one",  "ichi - XugE00"?, 
["two", "ni - 1u4E8C"P, 
["three", "san - YugE09"), 
[("four", "shi - 1u56DB"P, 
("five", "go - Mu4E94"), 
(six",  "roku - Au516D"j, 
["seven", "shichi - 1ugE03"), 
("eight", "hachi - 1u516B"), 
("nine", "kyu - 1ugqE5D"), 
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["ten", — "ju - Vus341") 
5 
Runnable runner = new Runnable() £ 
public void run() £ 
JFrame frame = new JFrame("Label Header"); 
frame.setDefaultClose0peration(JFrame.EXIT_ON CLOSE); 
String headers[] = ("English", "Japanese"y; 
JTable table = new JTable(rows, headers); 
JScrollPane scrollPane = new JScrollPane(table); 


Icon redIcon = new DiamondIcon(Color.RED); 
Icon bluelcon = new DiamondIcon(Color.BLUE); 


Border headerBorder = UlManager.getBorder("TableHeader.cellBorder"); 
JLabel bluelabel = new JLabel(headers[0], bluelcon, JLabel.CENTER); 
blueLabel.setBorder(headerBorder); 

JLabel redlLabel = new JLabel(headers[1], redIcon, JLabel.CENTER); 
redLabel.setBorder(headerBorder); 

TableCellRenderer renderer = new JComponentTableCellRenderer(); 


TableColumnModel columnModel = table.getColumnModel (>); 


TableColumn columno = columnModel.getColumn(o0); 
TableColumn column1 = columnModel.getColumn(1); 


column0.setHeaderRenderer (renderer); 
columno.setHeaderValue(blueLabel); 


column1.setHeaderRenderer (renderer); 
column1.setHeaderValue(redLabel); 


frame.add(scrollPane, BorderLayout.CENTER); 
frame.setSize(300, 150); 
frame.setVisible(true); 
) 
$ 
EventQueue.invokelLater(runner); 
) 
) 


JTableHeader Class 


Each JTableHeader instance represents one of a set of headers for all the different columns. 
The set of JTableHeader objects is placed within the column header view ofthe JScroll1Pane. 
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You rarely need to work with the JTableHeader directly. Nevertheless, you can configure some 
characteristics of column headers. 


Creating a JTableHeader 


The JTableHeader has two constructors. One uses the default TableColumnModel, whereas the 
other explicitly specifies the model. 


public JTableHeader() 


JComponent headerComponent = new JTableHeader() 


public JTableHeader(TableColumnModel columnModel) 
JComponent headerComponent = new JTableHeader(aColumnModel) 


JTableHeader Properties 


As Table 18-11 shows, the JTableHeader has ten different properties. These properties allow 
you to configure what the user can do with a particular column header or how the column 
header is shown. 


Table 18-11. JTableHeader Properties 


Property Name Data Type Access 
accessibleContext AccessibleContext Read-only 
columnModel TableColumnModel Read-write bound 
draggedColumn TableColumn Read-write 
draggedDistance int Read-write 
reorderingAllowed boolean Read-write bound 
resizingAllowed boolean Read-write bound 
resizingColumn TableColumn Read-write 

table JTable Read-write bound 
UI TableHeaderUl Read-write 
UlClassID String Read-only 


Using Tooltips in Table Headers 


By default, if you set tooltip text for the table header, all of the column headers will share the 
same tooltip text. To specify a tooltip for a given column, you need to create or get the renderer, 
and then set the tooltip for the renderer. This is true for the individual cells, too. Figure 18-12 
shows how the results of this customization would appear. 
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English Japanese 
one 
tuvo 
three 
four 
five 
six 


Figure 18-12. Header tooltips 


The source for the customization in Figure 18-12 is shown in Listing 18-13. Unless you 
previously set the headers, it's not really necessary to check ifthe header for a specific column 
is null first. 


Listing 18-13. Showing Tooltip Text in a Table Header 


JLabel headerRenderer = new DefaultTableCellRenderer(); 

String columnName = table.getModel().getColumnName(0); 
headerRenderer.setText(columnName) ; 
headerRenderer.setToo1TipText ("Wave"); 

TableColumnModel columnModel = table.getColumnModel (>); 

TableColumn englishColumn = columnModel.getColumn(o); 
englishColumn.setHeaderRenderer((TableCellRenderer)headerRenderer); 


Customizing a JTableHeader Look and Feel 


The available set of UIResource-related properties for a JTableHeader is shown in Table 18-12. 
The five settings control the color, font, and border for the header renderers. 


Table 18-12. JTableHeader UlResource Elements 


Property String Object Type 
TableHeader background Color 
TableHeader.cellBorder Border 
TableHeader. font Font 
TableHeader. foreground Color 
TableHeaderUl String 


Note For an example of creating column headers spanning multiple columns, see CodeGuru at 
http://www. codeguru.com/java/Swing. 


717 


718 


CHAPTER 18 TABLES 


Editing Table Cells 


Editing JTable cells is nearly identical to editing JTree cells. In fact, the default table cell editor, 
DefaultCellEditor, implements both the TableCellEditor and TreeCellEditor interfaces, 
allowing you to use the same editor for both tables and trees. 

Clicking an editable cell will place the cell in edit mode. (The number of clicks required 
depends on the type of editor.) The default editor for all cells is a JTextField. Although this 
works great for many data types, it's not always appropriate for many others. So, you should 
either not support editing of nontextual information or set up specialized editors for your 
JTable. With a JTable, you register an editor for a particular class type or column. Then, when 
the table runs across a cell of the appropriate type, the necessary editor is used. 


Caution When no specialized editor is installed, the JTextField is used, even when it's inappropriate 
for the content. 


TableCellEditor Interface and DefaultCellEditor Class 


The TableCellEditor interface defines the single method necessary to get an editor cell for a 
JTable. The argument list for TableCellEditor is identical to the TableCel1Renderer, with the 
exception of the hasFocused argument. Because the cell is being edited, it's already known to 
have the input focus. 


public interface TableCellEditor extends CellEditor ( 
public Component getTableCellEditorComponent(JTable table, Object value, 
boolean isSelected, int row, int column); 


As described in Chapter 17, the DefaultCellEditor provides an implementation ofthe 
interface. It offers a JTextField as one editor, a JCheckBox for another, and a JComboBox for a third. 

As Table 18-13 shows, in most cases the default editor is the JTextField. Ifthe cell data can 
be converted to and from a string, and the class provides a constructor with a String argument, 
the editor offers the text representation of the data value for the initial editing value. You can 
then edit the contents. 


Table 18-13. Default JTable Editors 


Class Editor Information 
Boolean JCheckBox Centered 
Object JTextField Left-aligned 


Creating a Simple Cell Editor 


As a simple example of changing a non-String cell in a JTable, you can provide a fixed set of 
color choices to the user. Then when the user picks a color, you have the appropriate Color value to 
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return to the table model. The DefaultCellEditor offers a JComboBox for just this situation. After 
configuring the ListCellRenderer for the JComboBox to display colors properly, you have a 
TableCellEditor for picking colors. Figure 18-13 shows how this might appear. 


English Japanese Boolean 
pl ichi-— [w] 
2 ni-= Y 
3 san-= 
4 shi- 2 Y 
5 go-E 


Figure 18-13. JComboBox color editor 


Tip Any time you can predefine all the choices, you can use the JComboBox as your editor through 
DefaultCellEditor. 


Listing 18-14 shows the class that represents the TableCellRenderer for the Color 
column of the example shown in Figure 18-13 and the ListCellRenderer for the 
JComboBox TableCellEditor. Because of the many similarities of the two renderer 
components, their definitions are combined into one class. 


Listing 18-14. JComboBox As Table Cell Renderer 


import java.awt.*; 
import javax.swing.*; 
import javax.swing.table.*; 


public class ComboTableCellRenderer 
implements ListCellRenderer, TableCellRenderer f 
DefaultListCellRenderer listRenderer = new DefaultListCellRenderer(); 
DefaultTableCellRenderer tableRenderer = new DefaultTableCell1Renderer(); 


private void configureRenderer(JLabel renderer, Object value) ( 
if ((value != null) 88 (value instanceof Color)) f 
renderer.setIcon(new DiamondIcon((Color)value)); 
renderer.setText(""); 
) else £ 
renderer.setIcon(null); 
renderer.setText((String)value); 
) 
) 
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public Component getListCellRendererComponent(JList list, Object value, 
int index, boolean isSelected, boolean cellHasFocus) f 
listRenderer = 
(DefaultListCellRenderer)listRenderer.getListCellRendererComponent( 
list, value, index, isSelected, cellHasFocus); 
configureRenderer(listRenderer, value); 
return listRenderer; 


) 


public Component getTableCellRendererComponent(JTable table, Object value, 
boolean isSelected, boolean hasFocus, int row, int column) f 
tableRenderer = 
(DefaultTableCellRenderer)tableRenderer.getTableCellRendererComponent ( 
table, value, isSelected, hasFocus, row, column); 
configureRenderer (tableRenderer, value); 
return tableRenderer; 


y 


To demonstrate the use of this new combined renderer and show a simple table cell editor, 


the program shown in Listing 18-15 creates a data model in which one of the columns is a 
Color. After installing the renderer twice and setting up the table cell editor, the table can be 
shown and the Color column can be edited. 


Listing 18-15. Table Cell Editor Sample 


import javax.swing.*; 
import javax.swing.table.*; 
import java.awt.*; 


public class EditableColorColumn € 


public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
Color choices[] = [Color.RED, Color.ORANGE, Color.YELLOW, 
Color.GREEN, Color.BLUE, Color.MAGENTA); 

ComboTableCellRenderer renderer = new ComboTableCell1Renderer(); 
JComboBox comboBox = new JComboBox(choices); 
comboBox.setRenderer(renderer); 
TableCellEditor editor = new DefaultCellEditor(comboBox); 


JFrame frame = new JFrame("Editable Color Table"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
TableModel model = new ColorTableModel(); 

JTable table = new JTable(model); 
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TableColumn column = table.getColumnModel ().getColumn(3); 
column.setCellRenderer(renderer); 
column.setCellEditor(editor); 


JScrollPane scrollPane = new JScrollPane(table); 
frame.add(scrollPane, BorderLayout.CENTER); 
frame.setSize(400, 150); 
frame.setVisible(true); 
) 
5 
EventQueue.invokelLater(runner); 
) 
J 


Listing 18-16 shows the table model used for this example and the next one. 


Listing 18-16. Table Model 


import java.awt.*; 
import javax.swing.table.*; 


public class ColorTableModel extends AbstractTableModel ( 


Object rowData[][] = £ 
("1", "ichi - 1u4E0O0", Boolean.TRUE, Color.RED?, 
(£"2", "ni - ugE8C", Boolean.TRUE, Color.BLUE?, 
£"3", "san - u4E09", Boolean.FALSE, Color.GREEN?, 
(£"4", "shi - 1u5s6DB", Boolean.TRUE, Color.MAGENTA?, 
("5", "go - MugE94", Boolean.FALSE, Color.PINKj, 
5 
String columnNames[] = ("English", "Japanese", "Boolean", "Color"); 
public int getColumnCount() ( 
return columnNames. length; 


) 

public String getColumnName(int column) ( 

return columnNames [column] ; 

) 

public int getRowCount() ( 

return rowData.length; 

) 

public Object getValueAt(int row, int column) ( 

return rowData[row][column]; 

) 

public Class getColumnClass(int column) ( 
return (getValueAt(O, column) .getClass()); 
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public void setValueAt(Object value, int row, int column) £ 
rowData[row][column]=value; 
) 
public boolean isCellEditable(int row, int column) € 
return (column != 0); 
) 
) 


Creating a Complex Cell Editor 


Although the previous example demonstrates how to provide a fixed set of choices to the user 
in a combo box TableCellEditor, offering the JColorChooser as an option seems to be a better 
choice (at least, in the case of color selection). When defining your own TableCellEditor, you 
must implement the single TableCellEditor method to get the appropriate component. You 
must also implement the seven methods of the CellEditor because they manage and notify a 
list of CellEditorListener objects, as well as control when a cell is editable. Starting with an 
AbstractCellEditor subclass makes defining your own TableCel1Editor much simpler. 

By extending the AbstractCellEditor class, only the getCellEditorValue() method from 
the CellEditor methods requires customization for the editor. Doing that and providing a 
JButton that pops up a JColorChooser when clicked provides the entire editor component. 
Listing 18-17 shows the code for this custom editor. 


Listing 18-17. JColorChooser As Table Cell Editor 


import java.awt.*; 

import java.awt.event.*; 

import javax.swing.*; 

import javax.swing.table.*; 

public class ColorChooserEditor extends AbstractCellEditor 
implements TableCellEditor ( 


private JButton delegate = new JButton(); 
Color savedColor; 


public ColorChooserEditor() ( 
ActionListener actionListener = new ActionListener() ( 
public void actionPerformed (ActionEvent actionEvent) ( 
Color color = JColorChooser.showDialog( 
delegate, "Color Chooser", savedColor); 
ColorChooserEditor.this.changeColor(color); 
h 
E 
delegate.addActionListener(actionListener); 


) 
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public Object getCellEditorvalue() ( 
return savedColor; 
y 


private void changeColor(Color color) f 
if (color != null) £ 
savedColor = color; 
delegate.setIcon(new DiamondIcon(color)); 
h 
y 


public Component getTableCellEditorComponent (JTable table, Object value, 
boolean isSelected, int row, int column) 4 
changeColor((Color)value); 
return delegate; 
J 
, 


Figure 18-14 shows the ColorChooserEditor in action, with the associated table in the 
background. 


£ Color Chooser xj 


[Swatches | HSB | RGB | 


lol 
English Japanese Boolean Color 

1 ichi-= (v] 

2 ni-= Y + 

3 san-= + 

4 shi- 20 Y + 

5 go-H 


Preview 


| Sample Text Sample Text 


Cancel Reset 


Figure 18-14. Pop-up color editor 


A sample program using the new ColorChooserEditor is shown in Listing 18-18. The 
example reuses the earlier ColorTableModel data model shown in Listing 18-16. Setting up the 
ColorChooserEditor simply involves setting the TableCellEditor for the appropriate column. 
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Listing 18-18. Testing Another Custom Table Cell Editor 


import java.awt.*; 
import javax.swing.*; 
import javax.swing.table.*; 


public class ChooserTableSample ( 
public static void main(String args[]) ( 


Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("Editable Color Table"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
TableModel model = new ColorTableModel(); 
JTable table = new JTable(model); 


TableColumn column = table.getColumnModel ().getColumn(3); 


ComboTableCellRenderer renderer = new ComboTableCell1Renderer(); 
column.setCellRenderer(renderer); 


TableCellEditor editor = new ColorChooserEditor(); 
column.setCellEditor(editor); 


JScrollPane scrollPane = new JScrollPane(table); 
frame.add(scrollPane, BorderLayout.CENTER); 
frame.setSize(400, 150); 
frame.setVisible(true); 
) 
E 
EventQueue.invokeLater(runner); 
) 
) 


Printing Tables 


One of the newer features with JDK 5.0 is also one of the easiest to use: the ability to print 
tables. Through the simple method of public boolean print() throws PrinterException of 
JTable, you can print a large table across multiple pages on the printer. It will even spread the 
columns across multiple pages if you don't like the default behavior of fitting the table's entire 
width on each page. 

To demonstrate this behavior, Listing 18-19 takes the basic JTable sample code used to 
generate Figure 18-1, adds some more rows to the table, and adds a print button. 
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Listing 18-19. Printing Tables Sample 


import javax.swing.*; 
import java.awt.*; 
import java.awt.event.*; 
import java.awt.print.*; 


public class TablePrint ( 
public static void main(String args[]) ( 
final Object rows[][] = ( 
("one",  "ichi - 1ug4E00"?, 
["two", "ni - XuqE8C”), 
("three", "san - 1ugE09"?, 
[("four", "shi - Au56DB"P, 
("five", "go - MugE94"), 
("six",  "roku - Mus16D"?, 
[("seven", "shichi - 1ugE03"), 
("eight", "hachi - 1u516B"), 
("nine", "kyu - 1u4E5D"), 
("ten", "ju - Mu5341"), 
. Repeat section at least 10 times ... 
("one",  "ichi - 1u4E00"?, 
["two", "ni - XuqE8C”), 
("three", "san - 1ugE09"P, 
[("four", "shi - Au56DB"?, 
("five", "go - MugE94"), 
("six",  "roku - Mus16D"?, 
[("seven", "shichi - 1ugE03"), 
("eight", "hachi - Mu516B"), 
("nine", "kyu - 1u4E5D"), 
["ten", "ju - 1us341"), 
5 
final Object headers[] = ("English", "Japanese"); 
Runnable runner = new Runnable() £ 
public void run() £ 
JFrame frame = new JFrame("Table Printing"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
final JTable table = new JTable(rows, headers); 
JScrollPane scrollPane = new JScrollPane(table); 
frame.add(scrollPane, BorderLayout.CENTER); 
JButton button = new JButton("Print"); 
ActionlListener printAction = new ActionListener() ( 
public void actionPerformed(ActionEvent e) ( 
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try ( 
table.print(); 
) catch (PrinterException pe) ( 
System.err.println("Error printing: 
J 
) 
E 
button.addActionListener(printAction); 
frame.add(button, BorderLayout.SOUTH); 
frame.setSize(300, 150); 
frame.setVisible(true); 


+ pe.getMessage()); 


y 
E 
EventQueue.invokeLater(runner); 
J 
y 


After clicking the Print button, the user is prompted with a typical printer selection dialog 
box, as shown in Figure 18-15. 


General | Page Setup Appearance | 


Print Service 


Name: ¡LaserJet ly [ Propertis... 


Status: Accepting jobs 


Type: 
Info: Print To File 
Print Range Copies 
(5 An Number of copies: 1H 
O Pages To Y] Collate 


Cancel 


Figure 18-15. Print dialog box displayed by the printing tables example 


After the user clicks the Print button in the Print dialog box, the printing begins. A dialog 
window like the one shown in Figure 18-16 appears for each page printed. 
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O) Printing page 41... 


Figure 18-16. Printing progress dialog box displayed by the printing tables example 


Yes, it really is that easy to print a multiple-page table with JDK 5.0. The print() method 
returns a boolean, so you can discover if the user canceled the operation. 

For those looking for more control over the printing operation, there are several other 
overloaded versions of the print() method of JTable. Like the simple print() method, they all 
can throw a PrinterException. 

One print () version lets you specify the print mode: 


public boolean print(JTable.PrintMode printMode) 


The JTable.PrintMode argument is an enumeration of FIT_WIDTH and NORMAL. When not 
specified with the no-argument version of print(), the defaultis FIT_WIDTH. 
Another version lets you specify a page header or footer: 


public boolean print(JTable.PrintMode printMode, MessageFormat headerFormat, 
MessageFormat footerFormat) 


MessageFormat comes from the java.text package. The one argument to the header and 
footer formatting string is the page number. To display the page number, include (0) in your 
formatting string where you want the page number to appear. Both will appear centered on the 
page, with the header in a larger font. To demonstrate, change the print () call in Listing 18-19 
to the following (and add an import line): 


MessageFormat headerFormat = new MessageFormat("Page (0)"); 
MessageFormat footerFormat = new MessageFormat("- (0) -"); 
table.print(JTable.PrintMode.FIT_WIDTH, headerFormat, footerFormat); 


The final print () version is the all inclusive one, allowing you to not show the printer 
dialog box and configure what the default print request attribute set entails, such as how many 
copies to print. 


public boolean print(JTable.PrintMode printMode, MessageFormat headerFormat, 
MessageFormat footerFormat, boolean showPrintDialog, 
PrintRequestAttributeSet attr, boolean interactive) 


For those times when you desire no user interaction to print, consider using this last version. 
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Summary 


In this chapter, you explored the inner depths of the JTable component. You looked at custom- 
izing the TableModel, TableColumnModel, and ListSelectionModel for the JTable. You delved 
into both the abstract and concrete implementations of the different table models. In addition, 
you examined the inner elements of the various table models, such as the TableColumn and 
JTableHeader classes. You also looked into how to customize the display and editing of the 
JTable cells by providing a custom TableCellRenderer and TableCellEditor. Finally, you learned 
about printing tables via the new print() method. 

In Chapter 19, you'll explore the drag-and-drop architecture of the JFC/Swing component set. 


CHAPTER 19 


Drag-and-Drop Support 


Do...::-070> support allows a user to highlight something in one program or area of the 
screen, select it, and relocate it to another program or area of the screen. For example, in 
Microsoft Word, you can select a paragraph and drag it to a new location. 

As Java has evolved, not only has the printing support changed with nearly every release, 
butso has the drag-and-drop support. The last major change in drag-and-drop support happened 
with the J2SE 1.4 release. Prior releases had support that was extremely difficult to use, especially to 
get proper drag-and-drop behavior for complex (nontext) types. The JDK 5.0 version adds 
some bug fixes and enhancements to drag-and-drop support. 

You can implement drag-and-drop within your Java program in three ways: 


+ For the components that come with built-in support, just enable it by calling their 
setDragEnabled() method with an argument of true. Those components are JColorChooser, 
JFileChooser, JList, JTable, JTree, and all the subclasses of JTextComponent, except 
JPasswordField. 


* For components without built-in support, you typically just need to configure the 
TransferHandler for that component. 


+ You can also go directly to the classes found in the java.awt.dnd package. Thanks to the 
built-in support and configurability, this approach is rarely necessary. 


Built-in Drag-and-Drop Support 


Table 19-1 shows the components that offer built-in support for drag-and-drop. Initially, only 
droppingis enabled for the components that supportit, but after calling setDragEnabled(true) 
for the component in question, you can enable dragging, too, ifit's supported. The drag-and- 
drop capabilities of the Java platform involve the underlying java.awt.datatransfer package 
to move data around. Classes in this package allow you to describe the type of data to transfer. 
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Table 19-1. Components with Built-in Support for Drag-and-Drop 


Component Drag Drop 
JColorChooser Xx XxX 
JEditorPane XxX Xx 
JFileChooser XxX 
JFormattedTextField XxX Xx 
JList Xx 
JPasswordField Xx 
JTable 
JTextArea 
JTextField 


JTextPane 


TS 


JTree 


Note For security reasons, you cannot drag text out of a JPasswordField component. 


For the JColorChooser component, what you dragis a java.awt.Color object. The other 
oddball of the bunch is the JFileChooser, where you literally drag a java.io.File object around 
and drop itinto a drop target. Ifthe drop target doesn't support working with File objects, a 
string representing the path is dropped instead. 

As a simple demonstration, Listing 19-1 shows a program with two JColorChooser compo- 
nents on a single screen. The setDragEnabled(true) call is made for both choosers, so you can 
drag-and-drop colors between the two components with minimal coding effort. 


Listing 19-1. Dragging-and-Dropping Colors Across JColorChooser Components 


import javax.swing.*; 
import java.awt.*; 


public class DoubleColor ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() 4 
public void run() £ 
JFrame frame = new JFrame("Double Color Choosers"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


JColorChooser left = new JColorChooser(); 
left.setDragEnabled(true); 
frame.add(left, BorderLayout.WEST); 
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JColorChooser right = new JColorChooser(); 
right.setDragEnabled(true); 
frame.add(right, BorderLayout.EAST); 


frame.pack(); 
frame.setVisible(true); 
J 
5 
EventQueue.invokeLater(runner); 
y 
J 


Figure 19-1 shows this program in action, after dragging several colors. The drag area is the 
Preview panel at the bottom. Dropping doesn't adjust the Recent list on the right side of each 
color chooser, and you can drop across different color chooser panels. 
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Figure 19-1. Dueling JColorChoosers 


TransferHandler Class 


The magic of drag-and-drop happens because of the java.swing.TransferHandler class, intro- 
duced with the J2SE 1.4 release. “What's magical about it?” you might ask. With this class, you 
can pick which property you would like to be transferable in a drag-and-drop operation. 
When you call setDragEnabled(true) to tell a component to support the drag gesture, the 
component asks the installed TransferHandler what to transfer. If you don't like the default 
object being transferred, you can call the setTransferHandler() method of the component, 
passing in an appropriate replacement. You can also call setTransferHandler() when you want 
to enable drag-and-drop support for a component that doesn't come with support built in. 
The TransferHandler class has one public constructor: 


public TransferHandler(String property) 
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The parameter to the constructor represents the property of the component that you wish 
to transfer. In other words, you identify the JavaBeans component property as the transferable 
object for the drag-and-drop operation. 

For instance, to transfer the text label of a JLabel, you would do the following: 


JLabel label = new JLabel("Hello, World"); 
label.setTransferHandler(new TransferHandler("text")); 


Since JLabel doesn't have a setDragEnabled() method, you must tell the component what 
the start of the drag gesture is. Typically, this would be pressing the mouse button, so you 
would also need to add a MouseListener to the button. When you tell the TransferHandler to 
exportAsDrag(), that enables the dragging operation for the component. 


MouseListener listener = new MouseAdapter() ( 
public void mousePressed(MouseEvent me) f 
JComponent comp = (JComponent)me.getSource(); 
TransferHandler handler = comp.getTransferHandler(); 
handler.exportAsDrag(comp, me, TransferHandler.COPY); 
J 
5 


button.addMouseListener(listener); 


The default behavior when the drop gesture happens—releasing the mouse in this example— 
would drop what was registered with the TransferHandler. 
Listing 19-2 demonstrates a program that enables drag-and drop for the text in a JLabel. 


Listing 19-2. Dragging Text from a JLabel 


import javax.swing.*; 
import java.awt.*; 
import java.awt.event.*; 


public class Draglabel £ 
public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() £ 
JFrame frame = new JFrame("Drag Label"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


JLabel label = new JLabel("Hello, World"); 
label.setTransferHandler(new TransferHandler("foreground")); 
MouseListener listener = new MouseAdapter() ( 
public void mousePressed(MouseEvent me) ( 
JComponent comp = (JComponent)me.getSource(); 
TransferHandler handler = comp.getTransferHandler(); 
handler.exportAsDrag(comp, me, TransferHandler.COPY); 
) 
5 
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label.addMouseListener(listener); 
frame.add(label, BorderLayout.SOUTH); 


JTextField text = new JTextField(); 
frame.add(text, BorderLayout.NORTH); 


frame.setSize(300, 150); 
frame.setVisible(true); 
) 
5 
EventQueue.invokeLater(runner); 


. 


) 


Figure 19-2 shows this program during the drag operation. Notice howthe cursor changes 
to indicate the operation. 
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Figure 19-2. Dragging text from a JLabel to a JTextField 


If instead of dragging the text ofthe JLabel, you wanted to drag the foreground color, the 
only change to the program would be to the setTransferHandler() line: 


label.setTransferHandler(new TransferHandler("foreground")); 


Then, assuming you had some place to drop the color, as in the program in Listing 19-1, 
you could drag the foreground color out of the label to the JColorChooser, and then drop the 
color out ofthe JColorChooser into the JLabel. Since the TransferHandler is registered for a 
specific property of the component, there is no explicit code necessary to handle dropping. 
Instead, the setter method for the property passed into the handler constructor is notified of 
the change. 


Drag-and-Drop Support for Images 


Ifyou wish to transfer something other than a simple property, you need to create an implementa- 
tion ofthe Transferable interface, found in the java.awt.datatransfer package. Transferable 
implementations are typically meant for transfers through the clipboard, but by having your 
implementation be a TransferHandler subclass, you can use itto drag-and-drop the object. 
The three methods of the Transferable interface are shown here: 
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public interface Transferablef 
public DataFlavor[] getTransferDataFlavors(); 
public boolean isDataFlavorSupported(DataFlavor); 
public Object getTransferData(java.awt.datatransfer.DataFlavor) 
throws UnsupportedFlavorException, IOException; 


One common application for this is the ability to transfer images. The exposed property of 
a JLabel or JButtonis a javax.swing. Icon object, not a java. awt. Image object. While you can 
certainly transfer Icon objects within and across Java programs, a more useful behavior is to 
transfer Image objects to external entities, like Paint Shop Pro or Photoshop. 

To create a transferable image object, the InageSelection class, you must implement 
the three Transferable interface methods and override four methods of TransferHandler: 
getSourceActions(), canImport(), createTransferable(), and importData(). 


Note The class for transferring strings is called StringSelection. 


The getSourceActions() method needs to report which actions you are going to support. 
By default, this is the TransferHandler .COPY operation when a property is set via the constructor, or 
TransferHandler.NONE when itis not. Since the ImageSelection class implicitly uses the icon 
property to get the component's image, just have the method return TransferHandler.COPY: 


public int getSourceActions(JComponent c) ( 
return TransferHandler.CoPY; 


J 


There is also a TransferHandler.MOVE operation, but you typically don't want the image to 
be removed from the label it was copied from. 

You pass the canImport() method a component and an array of DataFlavor objects. You 
need to verify that the component is supported and one of the flavors in the array matches the 
supported set: 


private static final DataFlavor flavors[] = ([DataFlavor.imageFlavor); 


public boolean canImport(JComponent comp, DataFlavor flavor[]) f 
if (! (comp instanceof JLabel) 82 !(comp instanceof AbstractButton)) ( 
return false; 
J 
for (int i=0, n=flavor.length; i<n; i++) ( 
for (int j=0, m=flavors.length; j<m; j++) ( 
if (flavor[i].equals(flavors[3])) ( 
return true; 
Í 
J 
J 
return false; 


J 
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The createTransferable() method returns a reference to the Transferable implementation. 
When the clipboard paste operation is executed, or the drop gesture is performed while dragging, 
the Transferable object will be notified to get the object to transfer. 


public Transferable createTransferable(JComponent comp) ( 
// Clear 
image = null; 


if (comp instanceof JLabel) ( 
JLabel label = (JLabel)comp; 
Icon icon = label.getIcon(); 
if (icon instanceof Imagelcon) ( 
image = ((ImageIcon)icon).getImage(); 
return this; 
) 

j else if (comp instanceof AbstractButton) ( 
AbstractButton button = (AbstractButton)comp; 
Icon icon = button.getlIcon(); 
if (icon instanceof Imagelcon) ( 

image = ((ImageIcon)icon).getImage(); 
return this; 
) 
) 


return null; 


The importData() method is called when data is dropped into the component or pasted 
from the clipboard. It has two parameters: a JComponent to paste the clipboard data and the 
clipboard data via a Transferable object. Assuming the method receives a format supported by 


the Java platform, the component associated with the transfer handler gets a new image to display. 


public boolean importData(JComponent comp, Transferable t) ( 
if (comp instanceof JLabel) ( 
JLabel label = (JLabel)comp; 
if (t.isDataFlavorSupported(flavors[0])) f 
try ( 
image = (Image)t.getTransferData(flavors[0]); 
Imagelcon icon = new Imagelcon(image); 
label.setIcon(icon); 
return true; 
) catch (UnsupportedFlavorException ignored) f 
j catch (IOException ignored) ( 
J 


) 
j else if (comp instanceof AbstractButton) ( 


AbstractButton button = (AbstractButton)comp; 
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if (t.isDataFlavorSupported(flavors[0])) ( 
try ( 
image = (Image)t.getTransferData(flavors[0]); 
Imagelcon icon = new Imagelcon(image); 
button.setIcon(icon); 
return true; 
j catch (UnsupportedFlavorException ignored) ( 
$ catch (IOException ignored) ( 
) 
, 
J 
return false; 


J 


Putting all this code together with the three methods implemented for the Transferable 
interface produces Listing 19-3. 


Listing 19-3. Implementing a Draggable Image 


import java.awt.*; 

import java.awt.image.*; 

import java.awt.datatransfer.*; 
import java.io.*; 

import javax.swing.*; 


public class ImageSelection extends TransferHandler 
implements Transferable ( 


private static final DataFlavor flavors[] = (DataFlavor.imageFlavor); 
private Image image; 


public int getSourceActions(JComponent c) ( 
return TransferHandler.CoPY; 


J 


public boolean canImport(JComponent comp, DataFlavor flavor[]) ( 
if (! (comp instanceof JLabel) 88 !(comp instanceof AbstractButton)) ( 
return false; 
) 
for (int i=0, n=flavor.length; i<n; i++) ( 
for (int j=0, m=flavors.length; j<m; j++) ( 
if (flavor[i].equals(flavors[3])) ( 
return true; 
h 
) 
J 
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return false; 


J 


public Transferable createTransferable(JComponent comp) f 
// Clear 
image = null; 


if (comp instanceof JLabel) ( 
Jlabel label = (JLabel)comp; 
Icon icon = label.getIcon(); 
if (icon instanceof Imagelcon) ( 
image = ((ImageIcon)icon).getImage(); 
return this; 
. 

j else if (comp instanceof AbstractButton) ( 
AbstractButton button = (AbstractButton)comp; 
Icon icon = button.getlIcon(); 
if (icon instanceof Imagelcon) ( 

image = ((ImageIcon)icon).getImage(); 
return this; 
) 
) 
return null; 


J 


public boolean importData(JComponent comp, Transferable t) ( 
if (comp instanceof JLabel) ( 
Jlabel label = (JLabel)comp; 
if (t.isDataFlavorSupported(flavors[0])) ( 
try ( 
image = (Image)t.getTransferData(flavors[0]); 
Imagelcon icon = new Imagelcon(image); 
label.setIcon(icon); 
return true; 
j catch (UnsupportedFlavorException ignored) ( 
j catch (IOException ignored) ( 
) 


l 
j else if (comp instanceof AbstractButton) ( 


AbstractButton button = (AbstractButton)comp; 
if (t.isDataFlavorSupported(flavors[0])) ( 
try ( 
image = (Image)t.getTransferData(flavors[0]); 
Imagelcon icon = new Imagelcon(image); 
button.setIcon(icon); 
return true; 
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j catch (UnsupportedFlavorException ignored) ( 
) catch (IOException ignored) ( 
J 
y 
J 


return false; 


J 


// Transferable 
public Object getTransferData(DataFlavor flavor) ( 
if (isDataFlavorSupported(flavor)) ( 
return image; 
J 


return null; 


J 


public DataFlavor[] getTransferDataFlavors() ( 
return flavors; 


J 


public boolean isDataFlavorSupported(DataFlavor flavor) ( 
return flavors[0].equals (flavor); 
J 
y 


To test this, you need to create a program with a draggable JLabel or AbstractButton 
subclass. This is basically the same program as shown in Listing 19-2, but with only a JLabel 
with an associated image located in the center of the screen. 


Listing 19-4. Draggable Image 


import javax.swing.*; 
import java.awt.*; 
import java.awt.event.*; 


public class DragImage 1 
public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("Drag Image"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
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Icon icon = new Imagelcon("dog.;jpg"); 
JLabel label = new JLabel(icon); 
label.setTransferHandler(new Imageselection()); 
Mouselistener listener = new MouseAdapter() ( 
public void mousePressed(MouseEvent me) ( 
JComponent comp = (JComponent)me.getSource(); 
TransferHandler handler = comp.getTransferHandler(); 
handler.exportAsDrag(comp, me, TransferHandler. COPY); 
) 
5 
label.addMouseListener(listener); 
frame.add(new JScrollPane(label), BorderLayout.CENTER); 


frame.setSize(300, 150); 
frame.setVisible(true); 
J 
5 
EventQueue.invokeLater(runner); 
y 
) 


Figure 19-3 shows the program in action. 
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Figure 19-3. Dragging-and-dropping an image 
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Summary 


Drag-and-drop support in Swing is rich and varied. You get quite a bit of behavior for free for 
several of the standard components. Ifyou need more, you can dig down a layer at a time until 
you expose the features you need. 

Typically, you don'tneed to dig all the wayinto java. awt.dnd classes like DragSourceDragEvent, 
DragSourceDropEvent, or DropTargetDragEvent (to name a few). They are there and doing their 
work under the covers, but you don't need to worry about them. Instead, drag-and-drop support 
is typically delegated to the TransferHandler associated with a property of the component to 
drag. Just setDragEnabled(true) on that component, and you're ready to go. You can also set 
up drag-and-drop support for other items, such as images, by creating an implementation of 
the Transferable interface. 

In the next chapter, you'll explore Swing's pluggable look and feel architecture. You'll 
learn how to customize your user interfaces without changing the code for the program. 


CHAPTER 20 


The Pluggable Look and 
Feel Architecture 


Í. Chapter 19, you examined Swing's drag-and-drop support. In this chapter, you will take an 
in-depth look at the pluggable look and feel (PLAF) architecture that's available when you're 
working with the Swing component library. 

All aspects of the Swing components are Java-based. Therefore, no native source code 
exists, as there is with the AWT component set. If you don't like the way the components are, 
you can change them, and you often have many ways to do so. 

The abstract LookAndFeel class is the root class for a specific look and feel. Each one of the 
installable look and feel classes, as they're described by the UlManager.LookAndFeelInfo class, 
must be a subclass of the LookAndFeel class. The LookAndFeel subclass describes the default 
appearance of Swing components for that specific look and feel. 

The set of currently installed look and feel classes is provided by the UlManager class, which 
also manages the default display properties of all the components for a specific LookAndFeel. 
These display properties are managed within a special UlDefaults hash table. The display prop- 
erties are either tagged with the empty UlResource interface or are UI delegates and therefore a 
subclass of the ComponentUl class. These properties can be stored as either UlDefaults.LazyValue 
objects or UlDefaults.ActiveValue objects, depending on their usage. 


LookAndFeel Class 


Implementations of the abstract LookAndFeel class describe how each ofthe Swing components 
will appear and how the user will interact with them. Each component's appearance is controlled 
by a UI delegate, which serves as both the view and the controller in the MVC architecture. 
Each of the predefined look and feel classes is contained within its own package, along with its 
associated UI delegate classes. When configuring the current look and feel, you can use one of 
the predefined look and feel classes or create your own. When you create your own look and 
feel, you can build on an existing look and feel, such as the BasicLookAndFeel class and its UI 
delegates, instead of creating all the UI delegates from scratch. Figure 20-1 shows the class 
hierarchy of the predefined look and feel classes. 
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9-(Í [LookAndFeel] 

9 (Í [BasicLookAndFeel] 
[y MetalLookAndFeel 
Ey Motif_ookAndFeel 
O) SynthLookAndFeel 
9 (Í] WindowsLookAndFeel] 

a WindowsClassicLookAndFeel 

Ey MultiLookAndFeel 


Figure 20-1. LookAndFeel class hierarchy diagram 


Each of the look and feel classes has six properties, as shown in Table 20-1. 


Table 20-1. LookAndFeel Properties 


Property Name Data Type Access 

defaults UlDefaults Read-only 
description String Read-only 
1D String Read-only 
name String Read-only 
nativelLookAndFeel boolean Read-only 
supportedLookAndFeel boolean Read-only 


These properties are all read-only and mostly describe the look and feel. The defaults 
property is slightly different, though. Once you getits UlDefaults value, you can then modifyits 
state directly through its own methods. In addition, the UlDefaults for a LookAndFeel can be 
directly accessed and modified through the UlManager class. 

The nativeLookAndFeel property enables you to determine if a particular look and feel 
implementation is the native look and feel for the user's operating system. For instance, the 
WindowsLookAndFeel is native to any system running one of the Microsoft Windows operating 
systems. The supportedLookAndFeel property tells you if a particular look and feel implementa- 
tion can be used. With the WindowsLookAndFeel implementation, this particular look and feel 
class is supported only ifthe current operating system is Microsoft Windows. Where available, 
the MacLookAndFeel implementation is supported only on MacOS computers. MotifLookAndFeel 
and MetalLookAndFeel are native look and feel classes that are not locked to a particular oper- 
ating system. 


Listing the Installed Look and Feel Classes 


To discover which look and feel classes are installed in your current environment, ask the 
UlManager, as shown in Listing 20-1. The UlManager has a UlManager.LookAndFeelInfo][] 
getInstalledLookAndFeels() method that returns an array of objects providing the textual 
name (public String getName()) and class name (public String getClassName()) for all the 
installed look and feel classes. 
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Listing 20-1. Listing Looking and Feel Classes 


import javax.swing.*; 


public class ListPlafs ( 
public static void main (String args[]) ( 
UlManager.LookAndFeelInfo plaf[] = UlManager.getInstalledLookAndFeels(); 
for (int i=0, n=plaf.length; i<n; i++) [ 
System.out.println("Name: " + plaf[i].getName()); 
System.out.println(" Class name: " + plaf[i].getClassName()); 
hi 
y 
J 


Running the program might generate the following output. Your current system configu- 
ration and/or changes to future versions ofthe Swing libraries could alter this result somewhat. 


Name: Metal 

Class name: javax.swing.plaf.metal.MetalLookAndFeel 
Name: CDE/Motif 

Class name: com.sun.java.swing.plaf.motif.MotifLookAndFeel 
Name: Windows 

Class name: com.sun.java.swing.plaf.windows.WindowsLookAndFeel 


Note Ocean is not a look and feel in and of itself. Instead, it is a built-in theme of the Metal look and feel. 
This theme happens to be the default for Metal. 


Changing the Current Look and Feel 


Once you know which look and feel classes are available on your system, you can have your 
programs use any one of them. The UlManager has two overloaded setLookAndFeel() methods 
for changing the installed look and feel class: 


public static void setLookAndFeel(LookAndFeel newValue) throws 
UnsupportedLookAndFeelException 


public static void setLookAndFeel(String className) throws 
ClassNotFoundException, InstantiationException, IllegalAccessException, 
UnsupportedLookAndFeelException 


Although the first version might seem to be the more logical choice, the second one is 
the more frequently used version. When you ask for the installed look and feel classes with 
UlManager.getInstalledLookAndFeels(), you get back the class names as strings of the objects, 
not instances. Because of the exceptions that can occur when changing the look and feel, you 
need to place the setLookAndFeel() call within a try/catch block. If you're changing the look 
and feel for an existing window, you need to tell the component to update its appearance with 
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acalltothe public static void updateComponentTreeUI (Component rootComponent) method of 
SwingUtilities. Ifthe component hasn't been created yet, this isn't necessary. 
The following source fragment demonstrates changing a look and feel: 


try ( 
UlManager.setLookAndFeel (finalLafClassName) ; 
SwingUtilities.updateComponentTreeUl (frame); 
$ catch (Exception exception) ( 
JOptionPane.showMessageDialog ( 
frame, "Can't change look and feel", 
"Invalid PLAF", JOptionPane.ERROR_MESSAGE); 


Figure 20-2 illustrates the results of a demonstration program that can change the look 
and feel at runtime through either a JComboBox or JButton component. Frequently, you won't 
want to allow a user to change the look and feel; you may just want to set the look and feel at 
startup time. 
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Figure 20-2. Before and after changing the look and feel 
Listing 20-2 shows the complete source of the program shown in Figure 20-2. 


Listing 20-2. Changing the Look and Feel 


import java.awt.*; 

import java.awt.event.*; 
import javax.swing.*; 
import javax.swing.plaf.*; 


public class Changelook f 
public static void main (String args[]) ( 
Runnable runner = new Runnable() f 


public void run() 4 


final JFrame frame = new JFrame("Change Look"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
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ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
Object source = actionEvent.getSource(); 
String lafClassName = null; 
if (source instanceof JComboBox) f 
JComboBox comboBox = (JComboBox)source; 
lafClassName = (String)comboBox.getSelectedItem(); 
) else if (source instanceof JButton) f 
lafClassName = actionEvent.getActionCommand(); 
) 
if (lafClassName != null) ( 
final String finalLafClassName = lafClassName; 
Runnable runnable = new Runnable() £ 
public void run() £ 
try ( 
UlManager.setLookAndFeel (finalLafClassName) ; 
SwingUtilities.updateComponentTreeUl (frame); 
) catch (Exception exception) ( 
JOptionPane.shonMessageDialog ( 
frame, "Can't change look and feel”, 
"Invalid PLAF", JOptionPane.ERROR_MESSAGE); 
J 
h 
A 
EventQueue.invokeLater(runnable); 
) 
J 
5 


UlManager.LookAndFeelInfo looks[] = 
UlManager.getInstalledLookAndFeels(); 


DefaultComboBoxModel model = new DefaultComboBoxModel (); 
JComboBox comboBox = new JComboBox(model); 


JPanel panel = new JPanel(); 


for (int i=0, n=looks.length; i<n; i++) ( 
JButton button = new JButton(looks[i].getName()); 
model. addElement(1looks[i].getClassName()); 
button.setActionCommand(looks[i].getClassName()); 
button.addActionListener(actionListener); 
panel .add(button); 

) 


comboBox.addActionListener(actionListener); 
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frame.add(comboBox, BorderLayout.NORTH); 
frame.add(panel, BorderLayout.SOUTH); 
frame.setSize(350, 150); 
frame.setVisible(true); 
di 
E 
EventQueue.invokeLater(runner); 
) 
j 


Note Notice that the actual look and feel change is made in a call to EventQueue.invokeLater(). 
This is necessary because the handling of the current event must finish before you can change the look and 
feel, and the change must happen on the event queue. 


Besides programmatically changing the current look and feel, you can start up a program 
from the command line with a new look and feel. Just setthe swing.defaultlaf system property 
to the look and feel class name. For instance, the following startup line would start the ChangeLook 
program, making the Motif look and feel the initial look and feel. 


java -Dswing.defaultlaf=com.sun.java.swing.plaf.motif.MotifLookAndFeel ChangeLook 


If you want a different default look and feel every time a program starts up, you can create 
afile, swing.properties, under the Java runtime directory (jre by default) with the appropriate 
setting. The swing .properties file needs to be in the lib directory of the Java runtime directory 
(jre/lib). For instance, the following line would cause the initial look and feel to be Motif all 
the time, unless changed programmatically or from the command line. 


swing.defaultlaf=com.sun.java.swing.plaf.motif.MotifLookAndFeel 


In addition to the swing.defaultlaf setting, the swing .properties file supports several 
other entries, as listed in Table 20-2. Each property allows you to override the default settings 
for the predefined look and feel setup. The auxiliary and multiplexing look and feel classes 
support accessibility, among other things. They will be discussed later in this chapter, in the 
“Using an Auxiliary Look and Feel” section. 


Table 20-2. Swing Properties File Entries 


Property Name Default Value When Unset 
swing.defaultlaf javax.swing.plaf.metal.MetalLookAndFeel 
swing.auxiliarylaf None 

swing.plaf.multiplexinglaf javax.swing.plaf.multi.MultiLookAndFeel 
swing.installedlafs Metal, Motif, Windows 
swing.installedlaf.*.name N/A 

swing.installedlaf.*.class N/A 
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Tip The swing.installedlafs and swing .auxiliarylaf property settings are comma-separated 
lists of installed look and feel classes. 


You may notice that the Synth class shown in the class hierarchy in Figure 20-1 is not listed 
in the default set of installed look and feel classes. Synth requires a secondary configuration 
file; itisn't something you can just switch to on the fly without defining the custom appearances. 
This base look and feel class provides the framework for customization. You'll learn howto use 
the Synth look and feel in the “SynthLookAndFeel Class” section later in this chapter. 

The WindowsClassicLookAndFeel is used when the Windows XP style is not appropriate for 
the user's platform or the swing.noxp system property is set. 


Customizing the Current Look and Feel 


In Chapter 3, you looked at the MVC architecture as well as how the Swing components combine 
the view and the controller into a UT delegate. Now, you will delve into the UI delegate for the 
Swing components. Basically, if you don't like how a Swing component looks, you tell the 
UlManager to change it, and then it will never again look the way it did. 


UlManager Class 


Whenever you need to create a Swing component, the UlManager class acts as a proxy to get 
information about the currently installed look and feel. That way, if you want to install a new 
look and feel or change an existing one, you don't need to tell the Swing components directly; 
you just inform the UlManager. 

Each discussion of components in earlier chapters has been accompanied by a table of 
all the settings that can be changed through the UlIManager. In addition, this book's appendix 
provides an alphabetical listing of all available settings for JDK 5.0. Once you know the property 
string for the setting you want to change, you call the public Object UlManager.put(Object 
key, Object value) method, which changes the property setting and returns the previous 
setting (if one existed). For instance, the following line changes the background to red for 
JButton components. After you put a new setting into the UlManager class lookup table, any 
components created in the future will use the new value, Color.RED. 


UlManager.put("Button.background", Color.RED); 


Once you place new settings into the lookup table for the UlManager, the new settings will 
be used when you create a new Swing component. Old components aren't automatically 
updated; you must call their public void updateUI() method if you want them to be individu- 
ally updated (or call updateComponentTreeUI() to update a whole window of components). If 
you're creating your own components, or you're just curious about the current setting for one 
of the different component properties, you can ask the UlManager with one of the methods 
listed in Table 20-3. 
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Table 20-3. UlManager UlDefaults Getter Methods 


Method Name Return Type 
get0bject (Object key) Object 
getBorder (Object key) Border 
getColor(Object key) Color 
getDimension(Object key) Dimension 
getFont(Object key) Font 
getIcon(Object key) Icon 
getInsets(Object key) Insets 
getInt(Object key) int 
getString(Object key) String 
getUI(JComponent component) ComponentUI 


Each of these methods, except getUI (), has a second version that accepts a Locale argument 
for localization support. 

In addition to the defaults property, which is used when you call the different put() and 
get () methods, the UlManager has eight class-level properties. These are listed in Table 20-4, 
which includes two entries for 1ookAndFeel, with two different setter methods. 


Table 20-4. UlManager Class Properties 


Property Mame pe Ass 
auxiliaryLookAndFeels  LookAmdFeel[ ]  Read-omly 
crossPlatformLookAndFeelClassName String Read-only 
defaults UlDefaults Read-only 
installedLookAndFeels UlManager.LookAndFeelInfo[ ] Read-write 
lookAndFeel LookAndFeel Read-write 
lookAndFeel String Write-only 
lookAndFeelDefaults UlDefaults Read-only 
propertyChangeListeners PropertyChangeListener[ ] Read-only 
systemLookAndFeelClassName String Read-only 


The systemLookAndFeelClassName property allows you to determine what the specific look and 
feel class name is for the user's operating system. The crossPlatformLookAndFeelClassName prop- 
erty enables you to find out what class name, by default, represents the cross-platform look and 
feel: javax.swing.plaf.metal.MetalLookAndFeel. Initially, the lookAndFeelDefaults property and 
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the defaults property are equivalent. When you want to make changes to the look and feel, you 
use the defaults property. That way, the settings for a predefined look and feel don't change. 


UlManager.LookAndFeellnfo Class 


When you ask the UlManager for the list of installed look and feel classes, you're returned an 
array Of UIManager. LookAndFeelInfo objects. From this array, you can find out the descriptive 
name of the look and feel (from the name property of the LookAndFeel implementation), as well 
as the class name for the implementation. As Table 20-5 shows, the two settings are read-only. 


Table 20-5. UlManager.LookAndFeelInfo Properties 


Property Name Data Type Access 
className String Read-only 
name String Read-only 


UlDefaults Class 


The LookAndFeel classes and the UlManager use a special UlDefaults hash table to manage the 
Swing component properties that depend on the look and feel. The special behavior is that 
whenever a new setting is placed in the hash table with put (), a PropertyChangeEvent is generated 
and any registered PropertyChangeListener objects are notified. Many ofthe BasicLookAndFeel 
classes automatically register the Ul delegate to be interested in property change events at the 
appropriate times. 

If you need to change a number of properties at once, you can use the public void 
putDefaults(Object keyValueList[]) method, which causes only one notification event. With 
putDefaults(), the key/value entries alternate in a single-dimension array. For instance, to 
cause buttons to have a default background color of pink and a foreground color of magenta, 
you would use the following: 


Object newSettings[] = (["Button.background", Color.PINK, 
"Button.foreground", Color.MAGENTA); 

UlDefaults defaults = UlManager.getDefaults(); 

defaults .putDefaults(newSettings); 


Because UlDefaults is a Hashtable subclass, you can discover all the installed settings by using 
an Enumeration to loop through all the keys or values. To simplify things a little, Listing 20-3 
presents a program that lists the properties sorted within a JTable. It reuses several ofthe table 
sorting classes from Chapter 18. 


Note Feel free to change the UIDefaults property lister program in Listing 20-3 to support modification 
of property values. 
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Listing 20-3. Listing UlDefault Properties 


import javax.swing.*; 
import javax.swing.table.*; 
import java.awt.*; 

import java.awt.event.*; 
import java.util.*; 


public class ListProperties ( 
static class CustomTableModel extends AbstractTableModel ( 
Vector<Object> keys = new Vector<0bject>»(); 
Vector<O0bject> values = new Vector<Object>»(); 
private static final String columnNames[] = ("Property String", "Value"); 


public int getColumnCount() ( 
return columnNames. length; 


J 


public String getColumnName(int column) ( 
return columnNames [ column] ; 


J 


public int getRowCount() ( 
return keys.size(); 


J 


public Object getValueAt(int row, int column) € 
Object returnValue = null; 
if (column == 0) £ 
returnValue = keys.elementAt (row); 
j else if (column == 1) f 
returnValue = values.elementAt (row); 


J 


return returnValue; 


J 


public synchronized void uiDefaultsUpdate(UlDefaults defaults) f 
Enumeration newKeys = defaults.keys(); 
keys.removeA11Elements(); 
while (newKeys.hasMoreElements()) ( 

keys .addElement (newKeys.nextElement()); 
) 
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Enumeration newValues = defaults .elements(); 
values.removeAl11Elements(); 
while (newValues.hasMoreElements()) f 

values .addElement(newValues.nextElement()); 


) 


fireTableDataChanged(); 
) 
) 


public static void main(String args[]) ( 
Runnable runner = new Runnable() £ 
public void run() £ 
final JFrame frame = new JFrame("List Properties"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


final CustomTableModel model = new CustomTableModel (); 
model. uiDefaultsUpdate(UlManager.getDefaults()); 
TableSorter sorter = new TableSorter(model); 


JTable table = new JTable(sorter); 
TableHeadersorter.install(sorter, table); 


table.setAutoResizeMode(JTable.AUTO RESIZE ALL COLUMNS); 


UlManager.LookAndFeelInfo looks[] = 
UlManager.getInstalledLookAndFeels(); 


ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
final String lafClassName = actionEvent.getActionCommand(); 
Runnable runnable = new Runnable() 4 
public void run() ( 
try ( 
UlManager.setLookAndFeel (lafClassName); 
SwingUtilities.updateComponentTreeUl (frame); 
model .uiDefaultsUpdate(UlManager.getDefaults()); 
Y catch (Exception exception) ( 
JOptionPane.shonMessageDialog ( 
frame, "Can't change look and feel", 
"Invalid PLAF", JOptionPane.ERROR_MESSAGE); 
) 
y 
5 
EventQueue.invokelLater(runnable); 
) 
5 
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JToolBar toolbar = new JToo1Bar(); 

for (int i=0, n=looks.length; i<n; i++) 4 
JButton button = new JButton(looks[i].getName()); 
button.setActionCommand(looks[i].getClassName()); 
button.addActionListener(actionListener); 
toolbar.add(button); 


frame.add(toolbar, BorderLayout.NORTH); 
JScrollPane scrollPane = new JScrollPane(table); 
frame.add(scrollPane, BorderLayout.CENTER); 
frame.setSize(400, 400); 
frame.setVisible(true); 


) 
y; 
EventQueue.invokeLater(runner); 
) 

) 

Figure 20-3 shows an example of running the property lister. 
lx 

Metal | CDE/Motif | Windows 
Property String Value 

¡AuditoryCues.allAuditoryCues Ljava.lang.Object, 06438 
AuditoryCues.cueList Ljava.lang.Object,¡ 04380 
¡AuditoryCues.defaultCueList Ljava.lang.Object,¡ 91 cd0888 
¡AuditoryCues.noAuditoryCues Ljava.lang.Object,(01eb2c1b 
Button .background javax.swing.plaf. ColorUlResour... 
Button.border sun.swing.SwingLazyYalue(9c... 
Button.darkShadow javax.swing.plaf.ColorUlResour... 
Button.defaultButtonF ollowsFoc... [false 
Button.disabledText javax.swing.plaf. ColorUlResour... 
Button.disabledToolBarBorderB... |javax.swing.plaf. ColorUlResour... 
Button.focus javax.swing.plaf.ColorUlResour... 
Button.focusInpuimMap javax.swing.UlDefaults$LazyInp... 
Button.font javax.swing.plaf.metal.MetalLoo... 
Button. foreground javax.swing.plaf.ColorUlResour... 
Button.gradient [0.3, 0.0, javax.swing.plaf.Color... 
Button.highlight javax.swing.plaf.ColorUlResour... 
Button. light javax.swing.plaf.ColorUlResour... 
Button.margin javax.swing.plaf.InsetsUlResou... 
Button.rollover true 
Button.rolloverlconType ocean 


Figure 20-3. Sample property lister display 


Tip To reset a property to the default for the currently installed look and feel, setit to nul1. This will cause 
the component to get the original default from the look and feel. 
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UlResource Interface 


Every UlDefaults setting for the predefined look and feel classes uses a special marker inter- 
face, UlResource, that lets the UI delegate determine if a default value has been overridden. If 
you've changed a specific setting to a new value (for example, the Button .background setting to 
Color.PINK), then the UlManager won't replace this setting when the installed look and feel 
changes. This is also true of a call to setBackground(Color.PINK). Only when the value for a 
specific property implements the UIResource interface will the setting change when the look 
and feel changes. 

The javax.swing.plaf package contains many classes that implement the UIResource 
interface. For example, the ColorUTResource class treats Color objects as UlResource elements. 
Table 20-6 lists all ofthe predefined UTResource components available for customizing the 
installed look and feel. 


Table 20-6. UlResource Collection 


UlResource Implementation Wrapped Class/Interface 
ActionMapUTResource Map 
BasicBorders.ButtonBorder Border 
BasicBorders.FieldBorder Border 
BasicBorders.MarginBorder Border 
BasicBorders.MenuBarBorder Border 
BasicBorders.RadioButtonBorder Border 
BasicBorders.RolloverButtonBorder Border 
BasicBorders.SplitPaneBorder Border 
BasicBorders.ToggleButtonBorder Border 
BasicComboBoxEditor.UIResource ComboBoxEditor 
BasicComboBoxRenderer.UIResource ListCellRenderer 
BasicTextUI.BasicCaret Caret 
BasicTextUI.BasicHighlighter Highlighter 
BorderUlResource Border 
BorderUTResource.BevelBorderUlIResource Border 
BorderUTResource.CompoundBorderUTResource Border 
BorderUTResource.EmptyBorderUTResource Border 
BorderUTResource.EtchedBorderUlResource Border 
BorderUTResource.LineBorderUTResource Border 
BorderUTResource.MatteBorderUlIResource Border 
BorderUIResource.TitledBorderUlResource Border 


ColorUTResource Color 
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Table 20-6. UlResource Collection (Continued) 
UlResource Implementation 

Component InputMapUTResource 
DefaultListCellRenderer.UlIResource 
DefaultMenuLayout 
DefaultTableCellRenderer .UIResource 
DimensionUIResource 

FontUTResource 

IconUTResource 

InputMapUTResource 
InsetsUTResource 
JScrollPane.ScrollBar 
etalBorders.ButtonBorder 
etalBorders.Flush3DBorder 
etalBorders.InternalFrameBorder 
etalBorders.MenuBarBorder 
etalBorders.MenuItemBorder 
etalBorders.OptionDialogBorder 
etalBorders.PaletteBorder 
etalBorders.PopupMenuBorder 
etalBorders.RolloverButtonBorder 
etalBorders.ScrollPaneBorder 
etalBorders.TextFieldBorder 
etalBorders.ToggleButtonBorder 
etalBorders.ToolBarBorder 
etalCheckBoxIcon 


etalComboBoxEditor.UIResource 


etalIconFactory.PaletteCloselcon 


ScrollPaneLayout .UIResource 


The following code demonstrates the use of the ColorUTResource class to set the button 


Wrapped Class/Interface 
InputMap / Component InputMap 


ListCellRenderer 
LayoutManager / LayoutManager2 
TableCellRenderer 
Dimension 

Font 

Icon 

InputMap 

Insets 
JScrollBar 
Border 

Border 

Border 

Border 

Border 

Border 

Border 

Border 

Border 

Border 

Border 

Border 

Border 

Icon 
ComboBoxEditor 
Icon 


ScrollPaneLayout 


background to a value that will change when the installed look and feel changes. 


Color background = new ColorUIResource(Color.PINK); 


UlManager.put("Button.background", background); 
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Without the wrapped ColorUTResource constructor call, the color would remain pink after 
a look and feel change. 


Note Use of the specific UIResource implementation classes tends to be limited to those times when 
you're creating a custom look and feel or customizing an existing one. 


UlDefaults.ActiveValue, UlDefaults.LazyValue, and UlDefaults.ProxyLazyValue Classes 


Besides implementing the UlResource interface, elements in the UlDefaults lookup table can 
belazy or active ifthey implement one of the inner classes ofUIDefaults: LazyValue or ActiveValue. 
For example, since Color and Dimension objects aren't very resource-intensive, when such an 
element is placed in the UlDefaults table, the Color or Dimension is created and placed in the 
table immediately—this is called active. On the other hand, in the case of a resource like an 
Icon, and especially an ImageIcon, you want to defer creating and loading the icon class file 
until it's needed—this is called lazy. Another example of an element you might want to make 
lazy is a ListCellRenderer that needs a separate renderer for every JList component. Because 
you don't know how many renderers you'll need or which renderer will be installed, you can 
defer creation to a later time and get a unique version ofthe current renderer whenever you ask 
for one. 

Take alook atthe public Object makelcon(Class baseClass, String imageFile) method 
of LookAndFeel. In order to handle the late loading oficon image files, the LookAndFeel class can 
automatically create a LazyValue class for loading an Icon. Because the image file won't be 
loaded until later, you need to provide the icon loader with the location of the icon image file 
(baseClass) and the file name (imageFile). 


Object icon0bject = LookAndFeel.makeIcon(this.getClass(), "World.gif"); 
UlManager.put("Tree.leafIcon", icon0bject); 


Next, look at the UlDefaults.LazyValue definition and create a lazy version of the DiamondIcon. 


public interface UlDefaults.LazyValue ( 
public Object createValue(UlDefaults table); 
) 


In classes that implement the LazyValue interface, their constructors need to save any 
information that will be passed along to the real constructor through the createValue() interface 
method. To help with creating custom lazy values, the UIDefaults.ProxyLazyValue class provides a 
way of saving this information to pass along. There are four ways to use ProxyLazyValue to defer 
object creation, which each uses reflection to create the actual object, getting the specific how 
(and what) from the constructor arguments: 


+ public UlDefaults.ProxyLazyValue(String className): If object creation will use the 
no-argument constructor, just pass the class name as an argument. 


+ public UlDefaults.ProxyLazyValue(String className, String method): If object 
creation will use a factory method that doesn't require arguments, pass the factory 
method along with the class name. 
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+ public UlDefaults.ProxyLazyValue(String className, Object[] arguments): If object 
creation will use a constructor that requires some arguments, pass the class name and 
array of arguments to the ProxyLazyValue constructor. 


+ public UlDefaults.ProxyLazyValue(String className, String method, Object[] 
arguments): If object creation will use a factory method that does require arguments, 
pass the factory method name along with the class name and array of arguments. 


For the lazy diamond icon implementation that's about to be created, you'll need to pass 
state information that consists of the color, selected state, and dimensions. 

To test the lazy diamond icon, you can associate an instance ofUIDefaults.ProxyLazyValue to 
the Tree.openIcon setting, as follows: 


Integer fifteen = new Integer(15); 

Object lazyArgs[] = new Object[] [ Color.GREEN, Boolean.TRUE, fifteen, fifteen) ; 
Object lazyDiamond = new UlDefaults.ProxyLazyValue("DiamondIcon", lazyArgs); 
UlManager.put("Tree.openIcon", lazyDiamond); 


Together with the previous change of the Tree. leafIcon settingto the World. gificon, and 
using the default tree data model, the tree would look like Figure 20-4. 


£ Lazy Example -10/ xj 
JTree 
? colors 


o- 1 sports 
o- 3 food 


Figure 20-4. A tree created with lazy values 


Listing 20-4 shows the source code for the example that generated Figure 20-4 by using the 
two lazy values. 


Listing 20-4. Lazy UlResources 


import java.awt.*; 

import java.awt.event.*; 
import javax.swing.*; 
import javax.swing.plaf.*; 


public class LazySample ( 
public static void main (String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("Lazy Example"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
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Object iconObject = 
LookAndFeel.makelIcon(LazySample.class, "World.gif"); 
UlManager.put("Tree.leafIcon", icon0bject); 


Integer fifteen = new Integer(15); 
Object lazyArgs[] = 

new Object[] (£Color.GREEN, Boolean.TRUE, fifteen, fifteen); 
Object lazyDiamond = 

new UlDefaults.ProxyLazyValue("DiamondIcon", lazyArgs); 
UlManager.put("Tree.openIcon", lazyDiamond); 


JTree tree = new JTree(); 
JScrollPane scrollPane = new JScrollPane(tree); 


frame.add(scrollPane, BorderLayout.CENTER); 
frame.setSize(200, 200); 
frame.setVisible(true); 
) 
E 
EventQueue.invokelLater(runner); 
) 
) 


Unlike lazy values, active values act like instance-creation factories. Every time they're 
asked for a value with one ofthe get() methods of UlManager, a new instance is created and 
returned. The interface method is the same as that for the UlDefault .LazyValue interface; only 
the interface name is different. 


public interface UlDefaults.ActiveValue ( 
public Object createValue(UlDefaults table); 
J 


To demonstrate, Listing 20-5 defines a factory that constructs JLabel components. The 
text of the label will function as a counter to show how many labels have been created. When- 
ever the createValue() method is called, a new JLabel is created. 


Listing 20-5. Active Label Factory 


import javax.swing.*; 


public class Activelabel implements UIDefaults.ActiveValue ( 
private int counter = 0; 


public Object createValue(UlDefaults defaults) ( 
JLabel label = new JLabel(""+counter++); 
return label; 
) 
) 
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To create the component, you need to install the ActiveLabel class with UlManager.put(). 
Once the class is installed, each call to get () the key out of the UlManager results in a new 
component being created. 


UlManager.put(LABEL_FACTORY, new ActiveLabel()); 


Jlabel label = (JLabel)UIManager.get(LABEL_FACTORY); 


Figure 20-5 shows the component in use. Whenever the button is clicked, the 
UIManager .get() method is called, and the component is added to the screen. 


Jolxi 
012345678910 11 12 
13 14 15 16 17 18 19 20 21 22 
23 24 25 26 27 28 29 30 31 32 
33 34 35 36 37 38 39 40 41 42 
43 44 45 46 47 48 49 50 51 52 
53 54 55 56 57 58 59 60 61 62 
63 64 65 66 67 68 69 70 71 72 
Get 


Figure 20-5. Using active values 
Listing 20-6 shows the source for the sample program in Figure 20-5. 


Listing 20-6. Active UlResources 
import java.awt.*; 
import java.awt.event.*; 
import javax.swing.*; 
public class ActiveSample ( 
private static final String LABEL_FACTORY = "LabelFactory"; 
public static void main (String args[]) ( 
Runnable runner = new Runnable() f 
public void run() ( 
JFrame frame = new JFrame("Active Example"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
UlManager.put(LABEL_FACTORY, new ActiveLabel()); 


final JPanel panel = new JPanel(); 


JButton button = new JButton("Get"); 
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ActionListener actionListener = new ActionListener() ( 
public void actionPerformed(ActionEvent actionEvent) ( 
Jlabel label = (JLabel)UIManager.get(LABEL_FACTORY); 
panel.add(label); 
panel.revalidate(); 
) 
5 


button.addActionListener(actionListener); 


frame.add(panel, BorderLayout.CENTER); 
frame.add(button, BorderLayout. SOUTH); 
frame.setSize(200, 200); 
frame.setVisible(true); 
) 
y; 
EventQueue.invokeLater(runner); 
) 
) 


Note There is a special lazy class for creating an InputMap lazily: the UIDefaults.LazyInputMap 
class. 


Using Client Properties 


If changing all the UTResource properties known to the UIManager still doesn't give you the look 
and feel you desire, some ofthe UI delegate classes can provide their own customized capabilities 
that are hidden from API views. These customized capabilities are provided as client properties 
and are accessible from two JComponent methods: public final Object getClientProperty (Object 
key) and public final void putClientProperty(Object key, Object value). Keep in mind 
that the key and value here are of type Object. While typically the key will be a String and the 
value an object of any type, the key can also be an object of any type. 

Client properties tend to be attributes of the component that are specific to the look and 
feel. Instead of subclassing the look and feel delegate to expose a property through a pair of 
getter/setter methods, the get/put client property methods provide access to a private instance- 
level lookup table to store a new property setting. In addition, as when making changes to the 
UlDefaults, modifying the client properties of a component notifies any registered property 
change listeners of the component. 

Most of the specific client properties have already been discussed throughout this book 
with their respective components. Table 20-7 provides a single resource for finding all the 
configurable client properties. The left column shows the class the property is used in, excluding 
the package name. The middle column shows the property name, which can include both the 
raw text string and any class constants that are available. The right column contains the class 
type to store with the property name. Ifthe class type is a String, a list of valid values is provided, 
if appropriate. 
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Table 20-7. Swing's Client Properties 


Class Accessed By 
AbstractButton 


AbstractButton 
BasicButtonListener 
BasicButtonUI 


BasicComboBoxUI 
BasicEditorPaneUuI 
BasicEditorPaneUuI 


BasicHTML 
BasicHTML 
BasicHTML 
BasicLabelUI 
BasicListul 
BasicMenuTtemUl 


BasicMenulItemUI 


BasicMenuTtemUI 
BasicPopupMenuUI 
BasicRadioButtonUI 
BasicRootPaneUl 
BasicSliderul 
BasicTabbedPaneUul 
BasicTableUI 
BasicTextul 
BasicToggleButtonUI 
BasicTool1Barul 


BasicToo1BaruI 


BasicToo1Tipul 
BluePrintEngine 
DefaultCaret 
DefaultCaret 


Property Name 
hideActionText 


html / BasicHTML.propertyKey 
initialDefaultButton 
html / BasicHTML.propertyKey 


JComboBox.isTableCellEditor / 
BasicComboBoxUI.IS TABLE CELL_EDITOR 


JEditorPane.honorDisplayProperties / 
JEditorPane.HONOR_ DISPLAY PROPERTIES 


JEditorPane.w3cLengthUnits / 
JEditorPane.W3C_LENGTH_UNITS 


html.base / BasicHTML.documentBaseKey 
html / BasicHTML.propertyKey 
html.disable / BasicHTML.htmlDisable 
html / BasicHTML.propertyKey 


List.isFilelist 


html / BasicHTML.propertyKey 

maxTextWidth / BasicMenuTtemUI.MAX_TEXT_WIDTH 
maxAccWidth / BasicMenuItemUl.MAX_ACC_WIDTH 
doNotCancelPopup 

html / BasicHTML.propertyKey 
temporaryDefaultButton 
Slider.paintThumbArrowShape 


index to remove 


Table.isFileLlist 
JPasswordField.cutCopyAllowed 
html / BasicHTML.propertyKey 


JToo1Bar.focusedCompIndex / BasicToolBarUl. 
FOCUSED_COMP_ INDEX 


JToo1Bar.isRollover / BasicTool1BarUl. 
IS ROLLOVER 


html / BasicHTML.propertyKey 


_ arrow direction__ 


caretAspectRatio 


caretWidth 


Type 


Boolean 
View 
JButton 
View 


Boolean 


Boolean 


Boolean 


URL 
View 
Boolean 
View 
Boolean 
View 
Integer 
Integer 
Boolean 
View 
Object 
Boolean 
Integer 
Boolean 
Boolean 
View 


Integer 


Boolean 


View 
Integer 
Number 


Integer 
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Table 20-7. Swing's Client Properties (Continued) 


Class Accessed By 
DefaultCaret 


DefaultDesktopManager 


Property Name 
JPasswordField.cutCopyAllowed 


JDesktopPane.dragMode 


Type 
Boolean 
String; valid values are 


null, outline, and 
faster 


FrameView charset String 

GTKFileChooseruI GTKFileChooser.showDirectoryIcons Boolean 

GTKFileChooserul GTKFileChooser.showFilelcons Boolean 

JInternalFrame wasIconOnce / Boolean 
DefaultDesktopManager.HAS_BEEN_ICONIFIED 
PROPERTY 

JComponent nextFocus / JComponent .NEXT_FOCUS Component 

JComponent InputVerifier / JComponent.INPUT_VERIFIER_KEY InputVerifier 

JComponent _WhenInFocusedWindow / Hashtable 
JComponent .WHEN_1IN_FOCUSED WINDOW BINDINGS 

JComponent ToolTipText / JComponent.TOOL_TIP_TEXT_KEY String 

JComponent TransferHandler / TransferHandler 
JComponent. TRANSFER_HANDLER_KEY 

JComponent AncestorNotifier / AncestorNotifier 
JComponent . ANCESTOR_NOTIFIER_KEY 

JComponent labeledBy / JLabel.LABELED_BY_PROPERTY JComponent / Accessible 

JEditorPane charset String 

JLabel html / BasicHTML.propertyKey View 

JLayeredPane layeredContainerLayer / Integer 
JLayeredPane.LAYER_PROPERTY 

JPasswordField JPasswordField.cutCopyAllowed Boolean 

JPopupMenu JPopupMenu.firePopupMenuCanceled Boolean 

JTable JTable.autoStartsEdit Boolean 

JTable terminateEditOnFocusLost Boolean 

JTool1Bar JToolBar.isRollover Boolean 

etalBorders NoButtonRol lover / Boolean 
MetalBorders.NO_BUTTON_ROLLOVER 

etalBorders JInternalFrame.messageType Integer 

etalFileChooseruI FileChooser.useShellFolder Boolean 

etalIconFactory paintActive Boolean 

etalInternalFramew> JInternalFrame.messageType Integer 


TitlePane 
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Table 20-7. Swing's Client Properties (Continued) 


Class Accessed By 


MetalInternalFrameUl 


MetalRadioButtonUI 
MetalScrollBarUl 


MetalSliderul 


MetalTreeul 


MotifGraphicsUtils 
MotifGraphicsUtils 


PopupFactory 


SpringLayout 


SwingUtilities 
SynthEditorPaneUl 


SynthGraphicUtils 
SynthMenuTtemUl 
SynthToo1Tipul 


WindowsDesktopManager 


WindowsFileChooserul 
WindowsSl1iderUI 
WindowsTool1BarUI 


Property Name 


JInternalFrame.isPalette / 
etalInternalFrameUI.IS PALETTE 


html / BasicHTML.propertyKey 


JScrollBar.isFreeStanding / 
MetalScroll1BarUI.FREE_STANDING_PROP 


JSlider.isFilled / MetalSliderUl.SLIDER_FILL 


JTree.lineStyle / MetalTreeUI.LineStyle 


html / BasicHTML.propertyKey 
maxAccWidth / MotifGraphicsUtils.MAX_ACC_WIDTH 


force_heavy weight popup__/ 
PopupFactory.forceHeavyWeightPopupKey 


Springlayout.class 


html / BasicHTML.propertyKey 


JEditorPane.honorDisplayProperties / 
JEditorPane.HONOR_DISPLAY PROPERTIES 


html / BasicHTML.propertyKey 
html / BasicHTML.propertyKey 
html / BasicHTML.propertyKey 


JInternalFrame.frameType 


FileChooser.useShellFolder 
Slider.paintThumbArrowShape 
XPStyle.subclass 


Type 


Boolean 


View 


Boolean 


Boolean 


String; valid values are 
Angled (MetalTreeUI. 
LEG LINE STYLE STRING), 
Horizontal (MetalTreeUI 
.HORIZ_STYLE_STRINO), 
and None (MetalTreeUI. 
NO_STYLE_ STRING) 


View 

Integer 
Boolean 
SpringLayout. 
Constraints 
View 


Boolean 


View 
View 
View 


String; valid values are 
null and optionDialog 


Boolean 
Boolean 


String 


Note Many of the properties in Table 20-7 are used internally by the specific component delegate imple- 
mentations, and you'll never need to use them. Other properties, such as the drag mode for the desktop 
manager, were interim means to add capabilities while keeping the API unaltered until a new JDK version 


was released. 
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To demonstrate the use of client properties, the following two lines change the 
JToo1Bar.isRollover attribute of a JToo1Bar to Boolean. TRUE. Other toolbars might not want 
this attribute set to Boolean. TRUE and would therefore leave that setting at Boolean. FALSE. 


JToolBar toolbar = new JToolBar(); 
toolbar.putClientProperty("JToo1Bar.isRollover", Boolean.TRUE); 


Creating a New Ul Delegate 


Sometimes, modifying a few of the UIResource elements of the Swing component isn't quite 
enough to get the appearance or behavior you desire. When this is the case, you need to create 
a new UI delegate for the component. Each Swing component has its own UI delegate for 
controlling the view and controller aspects ofits MVC architecture. 


Table 20-8 provides a listing of the Swing components, the abstract class that describes 
the UI delegate for each component, and the specific implementations for the predefined 
look and feel classes. For instance, calling the getUIClassID() method of a JToo1Bar will 
return the class ID string of "Too1BarUI" for its UI delegate. If you then ask the UlManager for 
the specific implementation of this Ul delegate for the currently installed look and feel with a 
call to UlManager.get("Tool1BarUI"), an implementation of the abstract Too1BarUl class is 
returned. Therefore, ifyou want to develop a custom look and feel for the JToo1Bar component, 
you must create an implementation of the abstract Too1BarUI class. 


Table 20-8. Swing Component Delegates 


Swing Component 


Class 1D String 


Implementation Class 


JButton ButtonUI ButtonUI 
JCheckBox CheckBoxUI ButtonUI 
JCheckBoxMenuItem CheckBoxMenuItemUI MenuTtemUI 
JColorChooser ColorChooserul ColorChooserul 
JComboBox ComboBoxUI ComboBoxUI 
JComponent n/a ComponentUl 
JDesktopPane DesktopPaneUI DesktopPaneUI 
JEditorPane EditorPaneUI TextuI 
JFileChooser FileChooserul FileChooserul 
JFormattedTextField FormattedTextFieldUlI TextuI 
JInternalFrame InternalFrameUI InternalFrameUul 
JInternalFrame.JDesktopIcon DesktopIconUI DesktopIconUI 
JLabel LabelUI LabelUI 

JList Listul ListuI 

JMenu MenuUI MenultemUl 
JMenuBar MenuBarUl MenuBarUl 
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Table 20-8. Swing Component Delegates (Continued) 


Swing Component 
JMenultem 


JOptionPane 

JPanel 
JPasswordField 
JPopupMenu 
JPopupMenu.Separator 
JProgressBar 
JRadioButton 
JRadioButtonMenultem 
JRootPane 

JScrollBar 
JScrollPane 
JSeparator 

JSlider 

JSpinner 


JSplitPane 


u 


TabbedPane 
Table 


u 


JTableHeader 


u 


TextArea 


JTextField 


u 


TextPane 


JToggleButton 


u 


ToolBar 


JToolBar.Separator 


u 


ToolTip 


JTree 


JViewport 


Class ID String 
MenultemUul 


OptionPaneUI 
PanelUT 
PasswordFieldUI 
PopupMenuUI 
PopupMenuSeparatorUl 
ProgressBarUl 
RadioButtonUI 
RadioButtonMenuTtemUI 
RootPaneUl 
ScrollBarul 
ScrollPaneUuI 
Separatorul 
SlideruI 

Spinnerul 
SplitPaneUuI 
TabbedPaneUI 
TableuI 
TableHeaderul 
TextAreaUl 
TextFieldUI 
TextPaneUI 
ToggleButtonUI 
ToolBarUI 
ToolBarSeparatorUl 


Too1Tipul 


TreeUul 


ViewmportUl 


Implementation Class 
MenultemUul 


OptionPaneUI 
PanelUl 
TextUl 
PopupMenuUl 
Separatorul 
ProgressBarUl 
ButtonUl 
MenultemUl 


RootPaneUl 
ScrollBarul 
ScrollPaneUI 
Separatorul 
Sliderul 
Spinnerul 
SplitPaneUI 
TabbedPaneUI 
TableUl 
TableHeaderul 
Textul 
Textul 


Textul 
ButtonUI 
Tool1Barul 
Separatorul 
Too1TipUI 
TreeUul 


Viemportul 
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Note Classes such as Window, JFrame, and JApp1et are heavyweight components and therefore lack 
a Ul delegate. 


The PopupComboSample example from Chapter 13 demonstrated the creation of a new UI 
delegate. Listing 20-7 is a slightly changed customized ComboBoxUI piece, where the normal 
down arrow for showing the drop-down menu is replaced with a right arrow. 


Listing 20-7. Customized ComboBoxUT 


import javax.swing.*; 
import javax.swing.plaf.*; 
import javax.swing.plaf.basic.*; 


public class MyComboBoxUI extends BasicComboBoxUI ( 
public static ComponentUuI createUI(JComponent c) ( 
return new MyComboBoxUI(); 
y 
protected JButton createArrowButton() 1 
JButton button = new BasicArrowButton(BasicArrowButton.EAST); 
return button; 
y 
J 


To use the new UI delegate, you just need to create the class and associate it with the 
component using the setUI() method. 


JComboBox comboBox = new JComboBox(labels); 
comboBox. setUI ((ComboBoxUI)MyComboBoxUI.createUI(comboBox)); 


Changing the PopupComboSample from Chapter 13 (Listing 13-16) to show two combo 
boxes, with the custom ComboBoxUI on the top and the bottom without, results in the screen 
shown in Figure 20-6. 


-l0lx 
Chardonnay Mal 
Chardonnay = 


Figure 20-6. Using the new ComboBoxUT 
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Listing 20-8 shows the updated source used to produce Figure 20-6. 


Listing 20-8. Using Customized ComboBoxUlI 


import java.awt.*; 
import javax.swing.*; 
import javax.swing.plaf.*; 


public class PopupComboSample ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() 4 
public void run() ( 

String labels[] = ("Chardonnay", "Sauvignon", "Riesling", "Cabernet", 
"Zinfandel”, "Merlot", "Pinot Noir", "Sauvignon Blanc", "Syrah", 
"Gewirztraminer"); 

JFrame frame = new JFrame("Popup JComboBox"); 

frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


JComboBox comboBox = new JComboBox(labels); 
comboBox.setMaximumRowCount (5); 

comboBox. setUI ((ComboBoxUI)MyComboBoxUI.createUI(comboBox)); 
frame.add(comboBox, BorderLayout.NORTH); 


JComboBox comboBox2 = new JComboBox(labels); 
frame.add(comboBox2, BorderLayout. SOUTH); 


frame.setSize (300, 100); 
frame.setVisible (true); 
y 
5 
EventQueue.invokeLater(runner); 
) 
y 


If you want to use the new UI delegate for all components, you can let the UlManager know 
about the delegate before creating the components, instead of manually calling setUl() after 
creating one. In the example in Listing 20-8, you would add the following line: 


UlManager.put("ComboBoxUI", "MyComboBoxUI") 


If you did this, both combo boxes would then look the same. 

The actual creation of the Ul delegate is done somewhat indirectly, as shown by Figure 20-7. 
A call to the component constructor asks the UlManager for the Ul delegate class. The UlManager 
maintains the list of delegates in its defaults property, a UIDefaults object. When the UlDefaults 
is queried for the delegate, it goes back to the component to ask which delegate is needed. After 
it finds the appropriate delegate implementation, the UlDefaults object tells the ComponentUI 
to create it, resulting in the actual UT delegate class being created. Once the UI delegate is 
created, it needs to be configured for the state of the specific model. 
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Figure 20-7. Ul delegate creation sequence diagram 


Creating a New Look and Feel 


Unless a company wants you to customize everything to provide a unique experience, it typically 
isn't necessary to create a whole new look and feel from scratch. Usually, developers make 
minor modifications to an existing look and feel by providing some customized Ul delegates. 
However, if you do want to create a new look and feel class, you just need to create a subclass 
ofthe LookAndFeel class. You still must provide the UI delegates, but their classes can now be 
more hidden from the Swing components, since their usage will not be known directly from 
the javax. swing component class. 


Using the WindowsLookAndFeel on a Non-Windows Machine 


To demonstrate the creation of a new look and feel class, let's create a look and feel implemen- 
tation that cancels out the platform requirement for the Windows UI delegate. By simply 
overriding the public boolean isSupportedLookAndFeel() method to return true, you effec- 
tively remove the platform requirement for the Windows look and feel class. 


Note The Java license expressly forbids you from delivering applications that remove the platform 
requirements for the Windows look and feel class. So, you can work through the example here, as long as 
you don't deliver it. 


The class definition in Listing 20-9 shows how simple the creation of a new look and feel 
implementation can be. 
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Listing 20-9. Custom Look and Feel 


import javax.swing.UlDefaults; 
import com.sun.java.swing.plaf.windows.WindowsLookAndFeel ; 
public class MyWindows extends WindowsLookAndFeel ( 
public String getID() ( 
return "MyWindows”; 
y 
public String getName() ( 
return "MyWindows Look and Feel"; 
J 
public String getDescription() ( 
return "The MyWindows Look and Feel"; 
y 
public boolean isNativeLookAndFeel() ( 
return false; 
J 
public boolean isSupportedLookAndFeel() ( 
return true; 
J 
ñ 


If you use this Swing class on a non-Windows machine, you can get the look and feel to be 
the Windows look and feel. Just set your look and feel to be MyWindows and make the look and 
feel class file available. The class file only needs to be available in your CLASSPATH and will be 
started with the following command line: 


java -Dswing.defaultlaf=MyWindows ClassFile 


For the Windows look and feel change to work properly, you need to provide the image 
files used for the icons of the look and feel from within the icons subdirectory of the MyWindows 
directory structure. Table 20-9 lists those icons appropriate to the predefined look and feel 
types. The MyWindows look and feel needs all of the Windows image files. 


Note Although Ocean is a theme of Metal, it does provide ¡ts own set of images. 


Table 20-9. Look and Feel Image Files 


File Name Basic Metal Motif Ocean Windows 
close.gif Xx 
collapsed-rtl.gif Xx 
collapsed.gif XxX 
computer.gif XxX 
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Table 20-9, Look and Feel Image Files (Continued) 
File Name. Basie Metal Motif Ocean Windows 
mp 
DesktopIcon.gif Xx 

DetailsView.gif Xx 
directory.gif Xx 

Directory.gif X 
Error.gif Xx x XxX 
error.png Xx 

expanded.gif X 

file.gif Xx 

File.gif X 
floppy .gif Xx 

FloppyDrive.gif X 
hardDrive.gif X 

HardDrive.gif X 
homeFolder.gif Xx 

HomeFolder.gif Xx 
iconify-pressed.gif X 

iconify.gif X 

info.png Xx 

Inform.gif XxX Xx Xx 
JavaCup16.png XxX 

JavaCup32.png Xx 
ListView.gif X 
maximize-pressed.gif 
maximize.gif 
menu.gif 
minimize-pressed.gif 


minimize.gif 


A 


newFolder.gif 
NewFolder.gif X 
paletteClose-pressed.gif Xx 
paletteClose.gif Xx 
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Table 20-9. Look and Feel Image Files (Continued) 
File Name Basic Metal Motif Ocean Windows 
question. png Xx 
ScrollDownArrow.gi+f 
ScrollDownArrowActive.gif 
Scrol1KnobH.gif 
ScrollLeftArrow.gif 
ScrollLeftArrowActive.gif 
ScrollRightArrow.gif 
ScrollRightArrowActive.gif 
ScrollUpArrow.gif 


ScrollUpArrowActive.gif 
StandardBackground.gif 
TrayBottom.gif 
TrayLeft.gif 
TrayRight.gif 
TrayTop.gif 


AS 


TreeClosed.gif 
TreeCollapsed.gif 
TreeLeaf.gif XxX 
Tree0pen.gif XxX XxX 
upFolder.gif XxX 

UpFolder.gif Xx 
Warn.gif XxX XxX Xx 


warning.png Xx 


Note At the very least, images for the JOptionPane message types are needed within every look and 
feel. Typically, these are named Error.gif, Inform.gif, Question.gif, and Warn.gif, though that 
isn't an absolute requirement. 
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If you don't want to sidestep the “native” requirement of the Windows look and feel, you 
can install individual UI delegates, such as the following, which uses the Windows UI delegate 
for the JButton component: 


UlManager.put("ButtonUI","com.sun.java.swing.plaf.windows.WindowsButtonUI”). 


Adding UI Delegates 


Creating a new look and feel that has custom UI delegates involves creating a subclass of the 
LookAndFeel class. More likely, you'll create a subclass of BasicLookAndFeel or another predefined 
look and feel class, and then provide your custom delegates for some ofthe components. 

If you subclass the BasicLookAndFeel class, it has a protected void 
initClassDefaults(UlDefaults table) method to be overridden to install your custom UI 
delegates. Just put the delegates in the UlDefaults table for the look and feel, instead ofin your 
program that wants to use the new delegate. 

The extension to the MetalLookAndFeel in Listing 20-10 adds the previously defined 
MyComboBoxUI delegate (Listing 20-7) as the ComboBoxUI delegate for the look and feel. As you 
define more customized components, you can add them in a similar way. 


Listing 20-10. MyMetal Look and Feel 


import javax.swing.UlDefaults; 
import javax.swing.plaf.metal.MetalLookAndFeel; 
public class MyMetal extends MetalLookAndFeel £ 
public String getID() ( 
return "MyMetal"; 
y 
public String getName() ( 
return "MyMetal Look and Feel"; 
y 
public String getDescription() ( 
return "The MyMetal Look and Feel"; 
y 
public boolean isNativeLookAndFeel() ( 
return false; 
y 
public boolean isSupportedLookAndFeel() ( 
return true; 
y 
protected void initClassDefaults(UlDefaults table) ( 
super.initClassDefaults(table); 
table.put("ComboBoxUI", "MyComboBoxUI"); 


7172 
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Note When creating your own look and feel, be sure to copy or create icons for the JOptionPane pop-up 
windows. Unless you're customizing Ocean, these icons should be named Error.gif, Inform.gif, 
Question.gif, and Warn.gif, and they belong in the icons directory under the directory where the look 
and feel class file exists. 


Working with Metal Themes 


The Metal look and feel class (javax.swing.plaf.metal.MetalLookAndFeel) provides the means 
to define themes to describe the default settings for the colors, fonts, and all the UlDefaults 
managed by the UlManager. By allowing users to change themes, they can get preferred colora- 
tion or font sizes with minimal work from the developer. By developing corporate themes, you 
can easily customize an interface without creating new look and feel classes or manually inserting 
new settings into current UlDefaults. 


MetalTheme Class 


Table 20-10 lists the 49 different properties that are available through the Metal1Thene class. 
The various primary and secondary properties are abstract and must be implemented in a 
subclass. Of the remaining properties, the six whose names end with Font—controlTextFont, 
menuTextFont, subTextFont, systemTextFont, userTextFont, and windowTextFont—are also 
abstract and must be implemented by a subclass. The remaining properties, by default, reuse 
one of the 11 primary/secondary values (or black and white) for their settings. 


Table 20-10. MetalTheme Properties 


Property Name Data Type Access 

acceleratorForeground ColorUTResource Read-only 
acceleratorSelectedForeground ColorUTResource Read-only 
black ColorUTResource Read-only 
control ColorUTResource Read-only 
controlDarkShadow ColorUTResource Read-only 
controlDisabled ColorUTResource Read-only 
controlHighlight ColorUTResource Read-only 
controlInfo ColorUTResource Read-only 
controlShadow ColorUTResource Read-only 
controlTextColor ColorUTResource Read-only 


controlTextFont FontUTResource Read-only 
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Table 20-10. MetalTheme Properties (Continued) 


Property Name Data Type Access 

desktopColor ColorUTResource Read-only 
focusColor ColorUTResource Read-only 
highlightedTextColor ColorUTResource Read-only 
inactiveControlTextColor ColorUTResource Read-only 
inactiveSystemTextColor ColorUTResource Read-only 
enuBackground ColorUTResource Read-only 
enuDisabledForeground ColorUTResource Read-only 
enuForeground ColorUTResource Read-only 
enuSelectedBackground ColorUTResource Read-only 
enuSelectedForeground ColorUTResource Read-only 
enuTextFont FontUTResource Read-only 
name String Read-only 
primary1 ColorUlTResource Read-only 
primary2 ColorUTResource Read-only 
primary3 ColorUTResource Read-only 
primaryControl ColorUTResource Read-only 
primaryControlDarkShadow ColorUTResource Read-only 
primaryControlHighlight ColorUTResource Read-only 
primaryControlIntfo ColorUTResource Read-only 
primaryControlShadow ColorUTResource Read-only 
secondary1 ColorUTResource Read-only 
secondary2 ColorUlTResource Read-only 
secondary3 ColorUTResource Read-only 
separatorBackground ColorUTResource Read-only 
separatorForeground ColorUTResource Read-only 
subTextFont FontUTResource Read-only 
systemTextColor ColorUTResource Read-only 
systemTextFont FontUTResource Read-only 
textHighlightColor ColorUTResource Read-only 
userTextColor ColorUTResource Read-only 
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Table 20-10. MetalTheme Properties (Continued) 


Property Name Data Type Access 

userTextFont FontUTResource Read-only 
white ColorUTResource Read-only 
windowBackground ColorUTResource Read-only 
windowTextFont FontUTResource Read-only 
windowTitleBackground ColorUTResource Read-only 
windowTitleForeground ColorUTResource Read-only 
windowTitleInactiveBackground ColorUTResource Read-only 
windowTitleInactiveForeground ColorUTResource Read-only 


DefaultMetalTheme and OceanTheme Classes 


Contrary to the class name, the DefaultMetalTheme class is not the default Metal theme; the 
default is OceanTheme. DefaultMetalTheme calls itself the Steel theme and uses a blue and gray 
color scheme for the primary and secondary settings, respectively. OceanTheme, named Ocean, 
uses a light-blue palette with frequent gradient fills for backgrounds. 

To use the Steel theme instead ofthe Ocean theme, you need to set the swing.metalTheme 
system property to steel, as shown here: 


java -Dswing.metalTheme=steel ClassName 


Most people prefer the newer look of Ocean, but Steel is still available for backward- 
compatibility, as Ocean is new to 5.0. 

If you create your own Metal theme, you need to subclass either OceanTheme or 
DefaultMetalTheme, and then install the custom theme by setting the static currentTheme 
property of the MetalLookAndFeel class to your theme. 


MetalTheme myTheme = new MyTheme(); 
MetalLookAndFeel.setCurrentTheme(myTheme); 


Whereas most of the customizations of a MetalThene are related to fonts and colors, the 
public void addCustomEntriesToTable(UlDefaults table) method allows you to override the 
default UIDefaults settings for the Metal look and feel. Therefore, not only do themes customize 
the fonts and colors of the Swing components, but they also can customize any one of the 
many UlResource-related properties of the Swing components. 

The following code demonstrates how to set two of the scrollbar settings for a specific 
theme. Remember to tag these settings with the UlResource interface when appropriate, and 
don't forget to initialize the table argument by your superclass implementation (eventually, 
this would be Metal1Thenme). 
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public void addCustomEntriesToTable(UlDefaults table) f 
super.addCustomEntriesToTable(table); 


ColorUIResource thumbColor = new ColorUIResource(Color.MAGENTA) ; 
table.put("Scrollbar.thumb", thumbColor); 
table.put("ScrollBar.width", new Integer(25)); 


J 


The Metalworks system demo provided with the JDK installation (jdk1.5.01demoN 
jfoOWMetalworks) comes with examples for customizing themes. One of the themes it defines 
reads the theme color settings from a property file. Instead of needing to create a new class file 
every time you want to change the theme of your Swing application, you can read it from a file 
at runtime. 


name=Charcoal 
primary1=33,66,66 
primary2=66,99,99 
primary3=99,99,99 
secondary1=0,0,0 
secondary2=51,51,51 
secondary3=102,102,102 
black=255,255,255 
white=0,0,0 


Figure 20-8 shows the Charcoal theme just described used within the Metalworks demon- 
stration program. Figure 20-9 shows the Presentation theme it defines. 


Metalworks 
File Edit Views Theme Drag Help 


Untitled Message 1 


To: 
Subj: 


Figure 20-8. Charcoal theme within the Metalworks demonstration program 
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Metalworks 
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D Buy Stuff Now 
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LK Re: Re: Thank You 
[3 ud: nad _laka 


Figure 20-9. Presentation theme within the Metalworks demonstration program 


Using an Auxiliary Look and Feel 


Swing provides for multiple look and feel classes to be active at any one time through 

the MultiLookAndFeel, or as specified bythe swing.plaf.multiplexinglaf property in the 
swing.properties file. When multiple look and feel classes are installed, only one look and feel 
will be visual and paint the screen. The remaining versions are called auxiliary look and feel 
classes and tend to be associated with accessibility options, such as for screen readers. Another 
possible auxiliary look and feel is that of a logger, which records those components that are 
interacted with in a log file. 

Auxiliary look and feel classes are registered with the runtime environment by config- 
uring the swing.auxiliarylaf property within the swing.properties file. If multiple classes 
are specified, the entries need to be separated by commas. In addition to using the properties 
file, you can install a look and feel within a program by calling the public static void 
addAuxiliaryLookAndFeel(LookAndFeel lookAndFeel) method of UIManager. Once installed, 
the multiplexing look and feel class automatically creates and manages UI delegates for all 
the installed look and feel classes. 

To find out which auxiliary look and feel classes are installed, you can ask the UlManager 
through its public static LookAndFeel[ ] getAuxiliaryLookAndFeels() method. This returns 
an array of the actual LookAndFeel objects, unlike the UlManager . LookAndFeelInfo array returned 
by the getInstalledLookAndFeels() method. 
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Note Nothing stops multiple look and feel classes from rendering to the screen for the same component. 
It's the responsibility of the auxiliary look and feel creator to take care not to compete with the primary look 
and feel when rendering to the screen. 


SynthLookAndFeel Class 


The Synth look and feel is a full-fledged look and feel, not just a themed extension to Metal, 
Windows, or Motif. Instead of working with a UIResource table though, the class starts with a 
blank canvas and gets its entire definition from a single XML file. 


Configuring Synth 
The configuration of the Synth look and feel might go something like this: 


SynthLookAndFeel synth = new SynthLookAndFeel (>; 

Class aClass = SynthSample.class; 

InputStream is = aClass.getResourceAsStream("config.xml"); 
synth.load(is, aClass); 

UlManager.setLookAndFeel (synth); 


And what exactly goes into the configuration file, config.xml here? In your configuration 
file, you specify how you want the specific components used in your program to appear. This 
is commonly called skinning your application, or creating a custom skin. By simply modifying 
an XML file, the entire appearance of your program changes; no programming is required. 

The DTD is available from http: //java.sun.com/j2se/1.5.0/docs/api/javax/swing/ 
plaf/synth/doc-files/synth.dtd. The file format is fully described in http: //java.sun.com/ 
j2se/1.5.0/docs/api/javax/swing/plaf/synth/doc-files/synthFileFormat.html. The parser 
does not validate, so until tools are available to help automate the process, you'll need to use 
care in creating the XML file. 

There are many configuration options available with Synth, but the basic XML conceptis 
to define a style and bind itto a component. The <style> tag allows you to customize proper- 
ties like the font, colors, insets, and background or border image. 

To demonstrate, Listing 20-11 defines a custom style named button. Normally, the text 
will appear in bold 24-point, Monospaced font. When the mouse moves over the associated 
control, the font changes to a 48-point italic SansSerif font, and the background color changes 
to blue. When the component is pressed, the font changes again, this time to a 36-point bold- 
italic Serif font, and the background becomes red. The final part of the configuration file asso- 
ciates the style named button with the JButton control, via the <bind> tag. 
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Listing 20-11. Synth Configuration 


<synth> 
<style id="button”> 
<font name="Monospaced” size="24" style="BOLD"/> 
<state value="MOUSE_OVER"> 
<font name="SansSerif" size="48" style="ITALIC”/> 
<opaque value="TRUE"/> 
<color value="BLUE" type="BACKGROUND" /> 
</state> 
<state value="PRESSED"> 
<font name="Serif" size="36" style="BOLD AND ITALIC"/> 
<opaque value="TRUE"/> 
<color value="RED" type="BACKGROUND" /> 
</state> 
</style> 
<bind style="button" type="region" key="Button"/> 
</synth> 


Figure 20-10 shows what the component might look like on the screen by itself. 


£ Synth Sample 4 (01 x/ £ Synth Sample 


Hello, Synth 


Normal Mouse Over 


> syrensomple ES 


Pressed 


Figure 20-10. Synth sample button screens 
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Listing 20-12 contains the complete sample code used to generate Figure 20-10. 


Listing 20-12. Synth Sample 


import java.awt.*; 

import java.io.*; 

import java.text.*; 

import javax.swing.*; 

import javax.swing.plaf.synth.*; 


public class SynthSample ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() £ 
public void run() £ 
SynthLookAndFeel synth = new SynthLookAndFeel(); 
try ( 
Class aClass = SynthSample.class; 
InputStream is = aClass.getResourceAsStream("config.xml"); 
if (is == null) ( 
System.err.println("Unable to find theme configuration"); 
System.exit(-1); 
J 
synth.load(is, aClass); 

j catch (ParseException e) f 
System.err.println("Unable to load theme configuration"); 
System.exit(-2); 

) 

try ( 

UlManager.setLookAndFeel (synth); 

j catch (javax.swing.UnsupportedLookAndFeelException e) ( 
System.err.printlin("Unable to change look and feel"); 
System.exit(-3); 

) 

JFrame frame = new JFrame("Synth Sample"); 

frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 

JButton button = new JButton("Hello, Synth"); 

frame.add(button, BorderLayout.CENTER); 

frame.setSize(300, 200); 

frame.setVisible(true); 

) 
5 
EventQueue.invokelLater(runner); 
) 
) 
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Default Synth Properties 


The configuration file isn't limited to just styles and bindings. In fact, if you truly do want to 
set a UIResource property, you still can, but only a limited subset is available. The file located 
athttp://java.sun.com/j2se/1.5.0/docs/api/javax/swing/plaf/synth/doc-files/ 
componentProperties.html specifies the full set. It is much smaller than the list you'll find 

in this book's appendix. These settings are configured with either a <property> tag ora 
<defaultProperty> tag. Defaults end up in the UlDefaults table for the look and feel; properties 
are just that—settings for the specific control. Tags similar to the following would be placed 
within a specific <style> tag to be configured: 


<property key="ScrollPane.viemportBorderInsets" type="insets" value="5 5 5 5"/> 
or 


<object class="javax.swing.plaf.ColorUIResource" id="color"> 
<int>255</int> 
<int>0</int> 
<int>0</int> 
</object> 
<defaultsProperty key="Table.focusCellForeground” type="idref" value="color"/> 


Working with Synth Images 


Indirectly, using the SynthPainter class, you can provide images that can be used for borders 
around components. However, the image must be specially created, as the painter doesn't just 
draw the image. That one image must be used for components of all sizes, of that type, such as 
for all text fields. The painter shares the image across different-sized controls by breaking the 
component into multiple regions. The four corners are always drawn as is. The middle regions 
are stretched vertically and horizontally. 

Figure 20-11 shows a possible border image to use. Notice how there are curves around the 
corners, but the middle areas don't have curves. The curves stay fixed when the border is 
stretched. 


Figure 20-11. Text component border 


To use the image in Figure 20-11 within your configuration file, you need to use the 
<imagePainter> tag and specify an appropriate method attribute. These map directly to the 
paintXXX(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) 
methods of the SynthPainter class. Since this image will be used for painting the text field 
border, the method attribute should be set to textFieldBorder. You also need to specify the path 
to the image (its file name and path relative to the location specified as the second argument to 
the SynthLookAndFeel.load() method). Insets and colors are the other items you need to specify. 
Here's the full style definition for just such a usage. 
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<style id="textfield"> 
<opaque value="true" /> 
<state> 
<color value="*C2E2CF" type="BACKGROUND"/> 
<color value="*000000" type="TEXT_FOREGROUND" /> 
</state> 
<imagePainter method="textFieldBorder" path="text.png" 
sourcelnsets="3 3 3 3" paintCenter="false"/> 
<insets top="3" left="3" bottom="3" right="3"/> 
</style> 
<bind style="textfield" type="region" key="TextField"/> 


Adding a JTextField to the program in Listing 20-12 generates a screen similar to Figure 20-12. 
When you resize the screen, the text field border grows. Technically speaking, a similar definition 
would also work for a JTextArea, as there is no height restriction to the image being used here. 


Jal 


Hello, Synth 


Hello, Synthl 


Figure 20-12. Using the custom text component border 


Tip Much more is in store for the SynthLookAndFeel. In time, expect tools to help with the creation of 
the XML configuration files. Also expect to be able to purchase libraries that let you just plug in complete look 
and feel classes created with Synth. Be sure to explore SourceForge for just such a collection. 


Summary 


In this chapter, you explored the pluggable look and feel architecture of the Swing components. 
Because all aspects of the Swing components are written in the Java programming language, if 
you don't like a particular aspect of a component, you can simply change it. And changing itis 
what this chapter showed you how to do. 

First, you learned howto query for the preinstalled LookAndFeel classes and howto change 
your current look and feel. Next, you learned how to customize the current look and feel by 
modifying its UlDefaults through the UlManager. You saw how these default settings can imple- 
ment the UTResource interface so that the settings change when the look and feel class changes. 
In addition, you saw how these resources can implement the UlDefaults.LazyValue and 
UlDefaults.ActiveValue interfaces for better use of resources. Moreover, you saw how client 
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properties are hidden from the API view but are available for customizing the look and feel of a 
component. 

To customize the look and feel of various components, you explored creating new Ul delegates 
as well as new look and feel classes, some of which could be nonvisual or auxiliary. You also saw 
how the Metal look and feel contains a specialized behavior through its use of themes. Lastly, 
you explored customizing the Synth look and feel. 


In Chapter 21, you'll look at the Swing undo framework, which is used for designing undo- 
able and redoable operations. 


CHAPTER 21 


The Undo Framework 


l. Chapter 20, you discovered how to customize your Swing-based applications by examining 
the pluggable look and feel architecture support. In this chapter, you'll examine the Undo 
Framework provided with the JFC as part of the Swing packages. 

The Swing packages from Sun include a facility for supporting undo operations within 
your applications. It allows you to support undoable and redoable operations that change the 
state of your data. Although the framework is part of the Swing package hierarchy, it's usable 
within any application, not just component-based applications. 


Working with the Undo Framework 


Found in the javax.swing.undo package, the Undo Framework includes five classes, two inter- 
faces, and two exceptions. To support the Undo Framework, a related interface and event are 
included in the javax.swing.event package. At the root of it all is the UndoableEdit interface. 
The interface forms the basis for encapsulating operations that can be undone or redone using 
the Command design pattern. 


Note Although technically part of the JFC/Project Swing release as an element in the 
javax.swing.undo package, the undo facility actually belongs in the java.util package. Unfortunately, 
when Swing first came out, it needed to be usable within JDK 1.1. Because Swing text packages use this undo 
facility, that facility needed to be in the Swing package hierarchy. Because Sun couldn't alter the Core API set 
for JDK 1.1, you'll find the undo support as part of the JFC/Swing packages, and it is therefore usable under 
the old JDK 1.1, as well as the 1.2 and later platforms, where Swing is standard. 


The rootimplementation class of the undoable command is the AbstractUndoableEdit 
class. Don't let the class name fool you, though—it isn't abstract. The children ofthe root 
command are the CompoundEdit and StateEdit command classes. 

The CompoundEdit class allows you to combine multiple undoable operations, in which 
some ofthe undoable operations could be StateEdit objects that store state changes. The 
Swing text components create DefaultDocumentEvent commands when their contents change. 
The command is a subclass of CompoundEdit as well as an inner class of AbstractDocument. An 
additional encapsulated command is the UndoManager, which is a subclass of CompoundEdit. 
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The UndoManager manages the edit operations on an editable object by serving as an 
UndoableEditListener and responding to the creation of each UndoableEditEvent. When 
an UndoableEdit can't be undone, a CannotUndoException is thrown. In addition, when an 
UndoableEdit can't be redone, a CannotRedoException is thrown. 

If you want to create objects that support undoable and redoable operations, the objects 
need to implement the StateEditable interface, and they can use the UndoableEditSupport 
class to help manage the list of UndoableEdit objects. 

Before going into the details ofthe individual pieces ofthe Undo Framework, let's explore 
how to use it with the Swing text components. If this is all you want to do, you don't need to 
understand how the rest works. 


Using the Undo Framework with Swing Text 
Components 


The Swing text components already support the necessary undo and redo capabilities. You 
merely need to manage them with an UndoManager and tell the manager when to undo/redo 
something. 

As an example, consider a program that includes a JTextArea with two toolbar buttons for 
undoing and redoing a text operation, as shown in Figure 21-1. 


-lalx 


| Undo ] Redo 


don't wantto go] 


Figure 21-1. Undo Swing text component usage example 


To enable the JTextArea shown in Figure 21-1 to support undoable operations, you must 
attach an UndoableEditListener to the Document ofthe component. Using an UndoManager as 
the listener is all you need to do. First, you create the manager, and then you attach it. 


UndoManager manager = new UndoManager(); 
textArea.getDocument(). addUndoableEditListener(manager); 


Once the manager is attached to the document ofthe JTextArea, it will monitor all changes 
to the contents of the text area. Because each ofthe Swing text components has a Document data 
model, you can associate an UndoManager with each of these components directly. 

After attaching the manager to the text component, you must provide some means to tell 
the manager to undo/redo an operation. Normally this would be done through a menu selec- 
tion or a toolbar button selection. In Figure 21-1, this is done with the help of buttons on a 
JToo1Bar, with one button for each command. For the Undo button, you want the manager to 
undo an operation. Therefore, the ActionListener for the button should call the public void 
undo() method of the UndoManager. The Redo button's ActionListener should call the manager's 
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public void redo() method. The undo() method and redo() method each throws a different 
exception that must be dealt with. 

Because the functionality necessary for the Undo and Redo buttons is the same for all 
managers, you'll find a helper UndoManagerHelper class included in Listing21-1 to create Action 
objects for you. These objects can be used by a JMenuBar, JToo1Bar, or anything else that can 
respond with an ActionListener for dealing with the undo and redo operations. You need to 
ask the helper class for each Action, and then associate that Action with the appropriate 
component. For instance, the following five lines of source code will take a previously created 
UndoManager and add the necessary buttons for a JToo1Bar: 


JToolBar toolbar = new JToolBar(); 

JButton undoButton = new JButton(UndoManagerHelper.getUndoAction(manager)); 
toolbar.add(undoButton); 

JButton redoButton = new JButton(UndoManagerHelper.getRedoAction(manager)); 
toolbar.add(redoButton); 


Using the undo facility with the Swing text components is that easy. The UndoManagerHe]per 
class definition is shown in Listing 21-1. Ifyou don't like the default button labels (shown in 
Figure 21-1), additional methods are available that support customization. In addition, ifan 
exception is thrown during the undo/redo operation, a warning message pops up. The warning 
message and pop-up window title are also customizable. 


Listing 21-1. The UndoManagerHelper Class Definition 


import javax.swing.*; 
import javax.swing.undo.*; 
import java.awt.*; 

import java.awt.event.*; 


public class UndoManagerHelper ( 


public static Action getUndoAction(UndoManager manager, String label) ( 
return new UndoAction(manager, label); 

y 

public static Action getUndoAction(UndoManager manager) Í 

return new UndoAction(manager, 

(String)UlManager.get("AbstractUndoableEdit.undoText")); 

y 

public static Action getRedoAction(UndoManager manager, String label) ( 
return new RedoAction(manager, label); 

y 

public static Action getRedoAction(UndoManager manager) Í 

return new RedoAction(manager, 

(String)UlManager.get("AbstractUndoableEdit.redoText")) 
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private abstract static class UndoRedoAction extends AbstractAction ( 

UndoManager undoManager = new UndoManager(); 

String errorMessage = "Cannot undo"; 

String errorTitle = "Undo Problem"; 

protected UndoRedoAction(UndoManager manager, String name) ( 

super(name); 

undoManager = manager; 
J 
public void setErrorMessage(String newValue) ( 
errorMessage = newValue; 
J 
public void setErrorTitle(String newValue) ( 
errorTitle = newValue; 
J 
protected void shonMessage(Object source) ( 

if (source instanceof Component) ( 

JOptionPane.shonMessageDialog ((Component)source, errorMessage, 
errorTitle, JOptionPane.WARNING_ MESSAGE); 
) else £ 
System.err.println(errorMessage); 


de 
J 
J 


public static class UndoAction extends UndoRedoAction f 
public UndoAction(UndoManager manager, String name) ( 
super(manager, name); 
setErrorMessage("Cannot undo"); 
setErrorTitle("Undo Problem"); 
J 
public void actionPerformed(ActionEvent actionEvent) ( 
try [ 
undoManager.undo(); 
$ catch (CannotUndoException cannotUndoException) ( 
showMessage(actionEvent.getSource()); 
) 
) 
h 


public static class RedoAction extends UndoRedoAction f 
public RedoAction(UndoManager manager, String name) ( 
super(manager, name); 
setErrorMessage("Cannot redo"); 
setErrorTitle("Redo Problem"); 


J 
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public void actionPerformed(ActionEvent actionEvent) ( 
try ( 
undoManager.redo(); 
) catch (CannotRedoException cannotRedoException) ( 
showMessage(actionEvent.getSource()); 
J 
) 
y 
J 


Note One thing you can do to improve these helper actions is to have them enabled only when the particular 
operation is available. The AbstractUndoableEdit.redoText and AbstractUndoableEdit.undoText 
usages are listed in Table 21-1. 


The rest of the source for the example shown in Figure 21-1 is provided in Listing 21-2. 
With the help of the new UndoManagerHelper class, the most difficult part of using the Undo 
Framework with the Swing text components has been greatly simplified. 


Listing 21-2. UndoManager Example with Swing Text Components 


import javax.swing.*; 
import javax.swing.undo.*; 
import java.awt.*; 


public class UndoSample ( 
public static void main(String args[]) ( 
Runnable runner = new Runnable() £ 
public void run() £ 

JFrame frame = new JFrame("Undo Sample"); 
frame.setDefaultClose0peration(JFrame.EXIT_ON CLOSE); 
JTextArea textArea = new JTextArea(); 
JScrollPane scrollPane = new JScrollPane(textArea); 


UndoManager manager = new UndoManager(); 
textArea.getDocument().addUndoableEditListener(manager); 


JToolBar toolbar = new JToolBar(); 
JButton undoButton = 

new JButton(UndoManagerHelper.getUndoAction(manager)); 
toolbar.add(undoButton); 
JButton redoButton = 

new JButton(UndoManagerHelper.getRedoAction(manager)); 
toolbar.add(redoButton); 
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5 


frame.add(toolbar, BorderLayout.NORTH); 
frame.add(scrollPane, BorderLayout.CENTER); 
frame.setSize(300, 150); 
frame.setVisible(true); 


J 


EventQueue.invokeLater(runner); 


J 
y 


If you plan to use the Undo Framework only with the Swing text components, you can skip 
reading the rest ofthe chapter. On the other hand, if you want to use the framework with other 
components, or even in a noncomponent setting, you'll want to read the remaining sections, 
which describe the inner workings of the framework in more detail. 


The Command Design Pattern 


The undo facility ofthe javax.swing.undo package utilizes the Command design pattern, 
which has the following participants: 


Command: The UndoableEdit interface defines the interface for executing the 
undo/redo operations. 


Concrete Command: Instances of the AbstractUndoableEdit class, or more specifically 
its subclasses, implement the necessary Command interface. They bind the commands 
to the receiver (Document) to modify its contents. 


Client: In the case of the Swing text components, the Document does the creation of the 
actual AbstractUndoableEdit subclass, an AbstractDocument .DefaultDocumentEvent 
by default. 


Invoker: The UndoManager serves as the Invoker of the UndoableEdit command. Normally, 
someone else tells the Invoker when to do the invoking. However, it's the Invoker who 
notifies the specific UndoableEdit instance when to undo/redo the command. 


Receiver: The Document is the receiver of the command from the actual 
AbstractUndoableEdit subclass. It knows how to process the request. 
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If you were using the Undo Framework outside the Swing text components, the Document 
element would be replaced with a receiver specific to your client application. You would need 
to create your own UndoableEdit interface implementation to act as the Concrete Command 
for the pattern. Instead ofimplementing the interface directly, you merely need to subclass the 
AbstractUndoableEdit class to encapsulate the specific information about your command. 

The design pattern is quite powerful. No matter which command class you're using within 
the pattern, you can set up capabilities, such as macros for tasks along the lines of automated 
testing, because the Invoker can sequence the commands at its leisure. 


Undo Framework Components 


You've seen the Undo Framework in action with the Swing text components and reviewed the 
Command design pattern. Let's now look at the individual pieces of the framework. 


UndoableEdit Interface 


The first Undo Framework piece is the UndoableEdit interface, which has the following 
definition: 


public interface UndoableEdit ( 
// Properties 
public String getPresentationName(); 
public String getRedoPresentationName(); 
public boolean isSignificant(); 
public String getUndoPresentationName(); 
// Other Methods 
public boolean addEdit(UndoableEdit anEdit); 
public boolean canRedo(); 
public boolean canUndo(); 
public void die(); 
public void redo() throws CannotRedoException; 
public boolean replaceEdit(UndoableEdit anEdit); 
public void undo() throws CannotUndoException; 


This interface defines the operations that can be done to an object that should support 
undo and redo capabilities. In addition to describing the supported operations, the interface 
implicitly defines the three states that an undoable operation can be in, as shown in Figure 21-2. 
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redoQ Undoable | Redoable ] undoQ 


y ¿ 
A 7 


redo() undo() 


Figure 21-2. UndoableEdit states 


The flow between states goes as follows: 


Undoable state: When an UndoableEdit command is first created, the operation is in the 
Undoable state. The purpose of the die() method is to release resources for an UndoableEdit 
before the garbage collector decides to clean things up and to place the command in the 
Done state. Calling the undo() method either throws a CannotUndoException or causes the 
command to be undone and the state to change to Redoable. Calling the redo() method 
either throws a CannotRedoException or causes the command to be done again and the 
state to stay at Undoable. 


Redoable state: When the operation is in the Redoable state, the command has already 
been undone. Calling the die() method releases any resources and places the command 
in the Done state. Calling the undo() method either throws a CannotUndoException or 
causes the command to be undone again and the state to stay at Redoable. Calling the 
redo() method either throws a CannotRedoException or causes the command to be redone, 
returning the state to the Undoable state. 


Done state: When the operation is in the Done state, calling any of the undo(), redo(), or 
die() methods leaves the operation in the Done state. 


Some state changes aren't commonplace; however, all state changes are supported. 
The specifics are left to the Command that you're using (as described in the preceding “The 
Command Design Pattern” section). For instance, Microsoft Word allows you to continuously 
repeat the last command ifthe capabilities make sense—such as when formatting a paragraph 
or just typing a phrase. 
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AbstractUndoableEdit Class 


The AbstractUndoableEdit class provides a default implementation for all the methods of the 
UndoableEdit interface. Although you might guess from the name that the class is abstract, it 
isn't. However, developers tend to work with subclasses of the class, not with a direct instance 
of this class. 

By default, AbstractUndoableEdit commands are significant (where isSignificant() 
returns true). What significance you place on the significant property setting depends on 
your usage of the command. In addition, the class restricts repetition of undoable state changes. 
Unless overridden by a subclass, exceptions are thrown if you try to redo something in the 
Undoable state or undo something in the Redoable state. The class doesn't support adding or 
replacing UndoableEdit operations. 

The default presentation names for the undoPresentationName and redoPresentationName 
properties are Undo and Redo, respectively. These are found by looking up the UTResource- 
related properties shown in Table 21-1. There is no default for the presentationName property. 
Subclasses should provide at least a presentation name to provide something more meaningful 
than the default settings. 


Table 21-1. AbstractUndoableEdit UlResource Elements 


Property String Object Type 
AbstractUndoableEdit.undoText String 
AbstractUndoableEdit.redoText String 


Tip By having the Undo and Redo presentation names as UIResource elements, they can be translated 
to foreign languages, with their new text available in the same way as other UTResource elements. 


CompoundEdit Class 


The CompoundEdit class allows you to combine multiple undoable operations into a single 
operation. For instance, you may want to combine all the keystrokes for typing a whole word 
into a single CompoundEdit command. This would allow you to continuously redo the typing of 
a whole word in multiple places. Without combining the separate keystrokes, redoing the last 
command would redo only the last single keystroke. 

The CompoundEdit class uses a read-only inProgress property to report whether the command 
is still being combined. Initially, the property is true. When in progress, additional commands 
can be added to the compound command with addEdit(UndoableEdit). To mark the end ofa 
set of commands, you call the end() method. Only after you combine all the commands can 
they be undone or redone. Figure 21-3 illustrates this. 
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Figure 21-3. CompoundEdit states 


With a CompoundEdit, if you undo() the edit, all added commands are undone. This is the 
same with redo(): All commands in the set are redone. 


UndoManager Class 


The UndoManager class is a specific subclass of CompoundEdit that tracks the history of edit 
commands, potentially for an entire application. The number of undoable commands the 
manager can track is defined by a configurable limit property whose initial value is 100. 

When isInProgress() reports true for a specific CompoundEdit, the UndoManager acts some- 
what like a backward CompoundEdit, in which individual edits can be undone and redone. Once 
end() has been called, the UndoManager acts like a CompoundEdit, but without the ability to undo 
or redo individual edit commands. In addition, the UndoManager has one more available state— 
Undoable or Redoable—*for when the manager has undone at least one command, can still 
undo more, but can also redo the undone command(s). 
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Besides being able to directly add editable operations with addEdit (), the manager also 
serves as an UndoableEditListener. When the UndoableEditEvent happens, the listener adds 
the event's UndoableEdit command to the manager with addEdit(). In addition, you can clear 
the edit queue with public void discardA11Edits(). After the manager receives the end() method, 
the sequence goes back to looking like Figure 21-3, leaving the bottom three states (Undoable, 
Redoable, and Done) shown in the chart. The whole sequencing is shown in Figure 21-4. 


redo()/undo() redo() [all not redone] / undo [all not undone] 
Empt | f  Undoable or | 
py ( Redoable 


redo() [all redone]-._ A Ado() [all undone] 


undo [all not undone] () [all not redone] 


redo() [all redone] 


Any State | R / f 
but Done addEdit() ”, Undoable | | Redoable 


5 ES le > Ea undo() [all undone] se ll 
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die() 
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Figure 21-4. UndoManager states 


Keep in mind that certain undo() and redo() calls can throw exceptions. In addition, when 
you ask the UndoManager to undo or redo an edit command, the request undoes (or redoes) all 
commands up to the last significant one. 

The transformation ofthe UndoManager into a CompoundEdit might seem confusing to some 
users. This transformation allows you to have a secondary UndoManager for certain subopera- 
tions that, once completed, become a single CompoundEdit to be passed along to the primary 
UndoManager. 
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Note Some developers might find it useful to extend the UndoManager to expose the UndoableEdit list 
that it is managing. Then they can display the presentation names of the various edit commands. Fortunately 
(or unfortunately), by default, these aren't exposed. 


UndoableEditListener Interface and UndoableEditEvent Class 


The UndoManager implements the UndoableEditListener interface so that it can be notified 
when undoable operations happen. The listener has the following definition: 


public interface UndoableEditListener extends EventListener ( 
public void undoableEditHappened(UndoableEditEvent undoableEditEvent); 
y 


The UndoableEditListener uses an UndoableEditEvent to tell interested objects when a 
command that can be undone has happened. The UndoableEditEvent class includes one property, 
edit, which returns the UndoableEdit object for the event: public UndoableEdit getEdit(). 

Of all the classes in the Swing-related packages, only the AbstractDocument class (as defined 
in the Document interface) comes with built-in support to add these listeners. When creating 
your own classes that support undoable operations, you'll need to maintain your own list of 
listeners with the help ofthe UndoableEditSupport class, described next. 


UndoableEditSupport Class 


The UndoableEditSupport class is similar to the JavaBeans-related classes of 
PropertyChangeSupport and VetoableChangeSupport. All three of these classes manage 
a list of a specific type of listener. In the case of the UndoableEditSupport class, that 
type of listener is the UndoableEditListener. You add listeners with public void 
addUndoableListener(UndoableEditListener) and remove them with public void 
removeUndoableListener(UndoableEditListener). 

When you want to notify listeners that an UndoableEdit operation has happened, you call 
the public void postEdit(UndoableEdit) method, which creates an UndoableEditEvent and 
calls the undoableEditHappened() method of each listener. 


Note The UndoableEditSupport class also includes support for combining multiple undoable edit 
commands into a CompoundEdit with the public void beginUpdate() and public void endUpdate(>) 
methods. 


The basic framework for the class usage follows in Listing 21-3. Normally, you tie the undo- 
able event to some other operation. In this example, it's tied to the moment an ActionEvent 
happens, and therefore any registered ActionListener objects need to be notified. 
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Listing 21-3. Managing UndoableEditListener Objects with UndoableEditSupport 


import javax.swing.undo.*; 
import javax.swing.event.*; 
import java.awt.event.*; 
import java.awt.*; 


public class AnUndoableComponent ( 
UndoableEditSupport undoableEditSupport = new UndoableEditSupport(this); 
ActionListener actionlListenerlist = null; 


public void addActionListener(ActionlListener actionListener) ( 
actionListenerList = AWTEventMulticaster.add(actionListener, 
actionListenerList); 


J 


public void removeActionListener(ActionListener actionListener) ( 
actionListenerList = AWTEventMulticaster.remove(actionListener, 
actionListenerList); 


J 


public void addUndoableEditListener( 
UndoableEditListener undoableEditListener) ( 
undoableEditSupport.addUndoableEditListener(undoableEditListener); 
J 


public void removeUndoableEditListener( 
UndoableEditListener undoableEditListener) ( 
undoableEditSupport.removeUndoableEditListener(undoableEditListener); 


J 


protected void fireActionPerformed(ActionEvent actionEvent) ( 

if (actionListenerlist != null) € 
actionListenerList.actionPerformed(actionEvent); 

) 
// Need to create your custom type of undoable operation 
undoableEditSupport.postEdit(new AbstractUndoableEdit()); 

) 

) 


A Complete Undoable Program Example 


Now that you've seen the main classes for the Swing Undo Framework, let's look at a complete 
example that defines a custom undoable class. The undoable class is a drawing panel in which 
each mouse click defines a point to be drawn in a polygon. Figure 21-5 shows the drawable 
panel in action, before and after an undo operation. 
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£ Drawing Sample 101 xj £ Drawing Sample - 101 xf 
Undo | Redo Undo | Redo 


Before Undo After Undo 


Figure 21-5. The undoable drawing panel at work 


The main program in Listing 21-4 looks practically identical to the earlier example of 
supporting undo and redo operations in a Swing text component, in Listing 21-2. You simply 
need to create an UndoManager to manage the undoable operations and associate itto the undo- 
able object. The usage of the Undo Framework works the same here, except that the undoable 
object is the yet-to-be-created UndoableDrawingPanel class (Listing 21-5). 


Listing 21-4. The UndoDrawing Test Driver 


import javax.swing.*; 

import javax.swing.undo.*; 

import java.awt.*; 

public class UndoDrawing ( 

public static void main(String args[]) ( 
Runnable runner = new Runnable() f 
public void run() £ 

JFrame frame = new JFrame("Drawing Sample"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 


UndoableDrawingPanel drawingPanel = new UndoableDrawingPanel(); 


UndoManager manager = new UndoManager(); 
drawingPanel.addUndoableEditListener(manager); 


JToolBar toolbar = new JTool1Bar(); 
JButton undoButton = 

new JButton(UndoManagerHelper.getUndoAction(manager)); 
toolbar.add(undoButton) ; 
JButton redoButton = 

new JButton(UndoManagerHelper.getRedoAction(manager)); 
toolbar.add(redoButton); 
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frame.add(toolbar, BorderLayout.NORTH); 
frame.add(drawingPanel, BorderLayout.CENTER); 
frame.setSize(300, 150); 
frame.setVisible(true); 
) 
y; 
EventQueue.invokeLater(runner); 
) 
) 


The UndoableDrawingPanel class is a component that draws a polygon within itself based 
on a set of points within the polygon. New points are added to the polygon whenever the 
mouse is released. Ifyou don't want the component to support undoable operations, you don't 
need to do anything beyond collecting points for the drawing panel. 

For the panel to support undoable operations, it must do two things: 


+ Ttmust maintain a listofUndoableEditListener objects. This can be easily done with the 
help of the UndoableEditSupport class, as shown earlier in Listing 21-3. 


+ The second task involves creating an UndoableEdit object, prior to any state changes, 
and posting it to the registered listeners. Because the state of the drawing panel is the 
polygon, this property must be exposed in the drawing class. 


Listing 21-5 shows the definition for the UndoableDrawingPanel class. Nothing in the class 
is particularly complicated. The important thing to remember when defining an undoable 
class is that the undoable event must be created before the state of the component changes. 
(The implementation class of the UndoableEdit interface, UndoableDrawEdit, is shown later, 
in Listing 21-6.) 


Listing 21-5. The UndoableDrawingPanel Main Component 


import javax.swing.*; 
import javax.swing.event.*; 
import javax.swing.undo.*; 
import java.awt.*; 

import java.awt.event.*; 


public class UndoableDrawingPanel extends JPanel ( 
UndoableEditSupport undoableEditSupport = new UndoableEditSupport(this); 
Polygon polygon = new Polygon(); 
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public UndoableDrawingPanel() ( 
MouseListener mouseListener = new MouseAdapter() ( 
public void mouseReleased(MouseEvent mouseEvent) ( 
undoableEditSupport.postEdit( 
new UndoableDrawEdit(UndoableDrawingPanel.this)); 
polygon.addPoint(mouseEvent.getX(), mouseEvent.getY()); 
repaint(); 
y 
E 
addMouseListener(mouseListener); 


J 


public void addUndoableEditListener( 
UndoableEditListener undoableEditListener) ( 
undoableEditSupport.addUndoableEditListener(undoableEditListener); 


) 


public void removeUndoableEditListener( 
UndoableEditListener undoableEditListener) ( 
undoableEditSupport.removeUndoableEditListener(undoableEditListener); 


J 


public void setPolygon(Polygon newValue) ( 
polygon = newValue; 
repaint(); 


J 


public Polygon getPolygon() ( 

Polygon returnValue; 
if (polygon.npoints == 0) ( 

returnValue = new Polygon(); 
y else £ 

returnValue = new Polygon( 

polygon.xpoints, polygon.ypoints, polygon.npoints); 

J 


return returnValue; 


J 


protected void paintComponent(Graphics g) ( 
super .paintComponent (g); 
g-drawPolygon(polygon) ; 
J 
ñ 


When defining the custom implementation of the UndoableEdit interface, you can choose 
to implement the complete interface, or you can subclass the AbstractUndoableEdit class and 
override any appropriate methods. More typically, you'll just subclass AbstractUndoableEdit. 
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The minimum methods to override are undo() and redo(), although you'll probably also choose 
to override getPresentationName() to give a better name to the undoable operation. 

Because the Command design pattern has the Concrete Command (that is, the 
UndoableEdit implementation) invoke the operation, the constructor must save any informa- 
tion necessary to make the operation undoable. In the case ofthe drawing panel, you need to 
save a reference to the panel and its current polygon. Then when the operation is asked to 
undo itself, the original polygon can be restored. To support redoing the undo operation, the 
undo() method must also save the new polygon; otherwise, the redo() operation wouldn't 
know how to change things back. It may sound like quite a bit of work, but it really isn't. The 
complete class definition for the UndoableEdit implementation follows in Listing 21-6. 


Listing 21-6. The UndoableDrawEdit Undoable Command 


import javax.swing.undo.*; 
import java.awt.*; 


public class UndoableDrawEdit extends AbstractUndoableEdit ( 
UndoableDrawingPanel panel; 
Polygon polygon, savedPolygon; 


public UndoableDrawEdit(UndoableDrawingPanel panel) ( 
this.panel = panel; 
polygon = panel.getPolygon(); 

J 


public String getPresentationName() ( 
return "Polygon of size " + polygon.npoints; 


J 


public void redo() throws CannotRedoException ( 
super.redo(); 
if (savedPolygon == null) ( 
// Should never get here, as super() doesn't permit redoing 
throw new CannotRedoException(); 
) else £ 
panel.setPolygon(savedPolygon); 
savedPolygon = null; 
J 
y 


public void undo() throws CannotUndoException ( 
super.undo(); 
savedPolygon = panel.getPolygon(); 
panel.setPolygon(polygon); 
y 
J 
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And that's it! The last two classes make the UndoDrawing example class (Listing 21-4) work. 
When creating your own undoable classes, you will need to subclass a nonundoable class and 
then add the necessary support to make it undoable. In addition, you will need to define an 
UndoableEdit implementation to support your specific class. 


Using an Outside Object to Manage Undo States 


In the previous example, it was the responsibility of your custom UndoableEdit implementation 
to maintain the before-and-after state of the undoable object. The Swing Undo Framework 
also supports the ability of an object outside the undoable edit implementation to manage the 
state. When using an outside object for state management, it isn't necessary to implement the 
UndoableEdit interface yourself. Instead, you can use the StateEdit class as the UndoableEdit 
implementation. The StateEdit class then relies on a class to implement the StateEditable 
interface to manage the before-and-after storage of the state of an undoable object (within a 
Hashtable). 


StateEditable Interface 


The StateEditable interface consists of two methods and a meaningless string constant. 


public interface StateEditable ( 
public final static String RCSID; 
public void restoreState(Hashtable state); 
public void storeState(Hashtable state); 

) 


An object that supports the undoing of its operations stores its state with the storeState(w» 
Hashtable) method. This is all the information about the state of the object that can change. 
Then restoring the state of the object is done in the restoreState(Hashtable) method. 

To demonstrate, let's see how to rewrite the UndoableDrawingPanel example. Using this 
interface with the updated, undoable drawing panel involves implementing the interface, and 
storing and getting the polygon shown earlier in Figure 21-5. That's because the polygon is the 
only state information we care about undoing. The source code is shown in Listing 21-7. 


Listing 21-7. The StateEditable Implementation of the Updated Component 


public class UndoableDrawingPanel2 extends JPanel implements StateEditable ( 


private static String POLYGON_KEY = "Polygon"; 

public void storeState(Hashtable state) ( 
state.put(POLYGON KEY, getPolygon()); 

J 
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public void restoreState(Hashtable state) ( 
Polygon polygon = (Polygon)state.get(POLYGON_ KEY); 
if (polygon != null) ( 
setPolygon(polygon); 
J 
y 
J 


The Hashtable that the restoreState() method returns contains only key/value pairs that 
changed. It's possible that the get() method of the Hashtable returns nul1 for something that 
you explicitly put () in the hash table. Therefore, as shown in Listing 21-7, you're required to 
add an if-null check after getting any state information from the hash table. 


StateEdit Class 


After you've implemented the StateEditable interface, you can use the StateEdit class as the 
UndoableEdit implementation. Where the previous UndoableDrawingPanel example created a 
custom UndoableDrawEdit, the new class creates a StateEdit instance. 

The StateEdit constructor accepts a StateEditable object that you're goingto change and 
an optional presentation name. After creating the StateEdit object, modify the StateEditable 
object and then tell the StateEdit to end() the modifications to the StateEditable object. 
When the StateEdit object is told that the modifications have ended, it compares the before- 
and-after states of the state editable object and removes any key/value pairs that didn't change 
from the hash table. You can then post the UndoableEdit to the list of UndoableEditListener 
objects through the list maintained by the UndoableEditSupport class. 


StateEdit stateEdit = new StateEdit(UndoableDrawingPanel2.this); 
// Change state of UndoableDrawingPanel2 
polygon.addPoint(mouseEvent.getX(), mouseEvent.getY()); 

// Done changing state 

stateEdit.end(); 

undoableEditSupport.postEdit(stateEdit); 


After the editis posted, the UndoManager manages the StateEdit instance of UndoableEdit, 
just like any other undoable edit object. The UndoManager can then request the StateEdit object 
to tell its StateEditable object to restore its previous state. This holds for any other 
UndoableEdit object. Therefore, no other source code needs to change. 


A Complete StateEditable/StateEdit Example 


The reworking of the UndoableDrawingPanel example is presented in Listing 21-8, with the 
differences from Listing 21-5 shown in boldface. This version uses the StateEditable/ 
StateEdit combination just described. The earlier test program is included as the main() 
method to keep the complete example together. With the exception of the class name change 
for the drawing panel, the test program didn't change and will still result in what you see in 
Figure 21-5, assuming the same set of points in the polygon. 
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Listing 21-8. The Updated UndoableDrawingPanel2 Main Component 


import javax.swing.*; 
import javax.swing.event.*; 
import javax.swing.undo.*; 
import java.awt.*; 

import java.awt.event.*; 
import java.util.Hashtable; 


public class UndoableDrawingPanel2 extends JPanel implements StateEditable ( 
private static String POLYGON_KEY = "Polygon"; 
UndoableEditSupport undoableEditSupport = new UndoableEditSupport (this); 
Polygon polygon = new Polygon(); 


public UndoableDrawingPanel2() ( 
MouseListener mouseListener = new MouseAdapter() ( 
public void mouseReleased(MouseEvent mouseEvent) ( 
StateEdit stateEdit = new StateEdit(UndoableDrawingPanel2.this); 
polygon.addPoint(mouseEvent.getX(), mouseEvent.getY()); 
stateEdit.end(); 
undoableEditSupport.postEdit(stateEdit); 
repaint(); 
) 
5 
addMouseListener(mouseListener); 
J 
public void addUndoableEditListener( 
UndoableEditListener undoableEditListener) ( 
undoableEditSupport.addUndoableEditListener(undoableEditListener); 
) 


public void removeUndoableEditListener( 
UndoableEditListener undoableEditListener) ( 
undoableEditSupport.removeUndoableEditListener(undoableEditListener); 
y 


public void storeState(Hashtable state) f 
state.put(POLYGON_KEY, getPolygon()); 
y 


public void restoreState(Hashtable state) ( 
Polygon polygon = (Polygon)state.get(POLYGON_KEY); 
if (polygon != null) ( 
setPolygon(polygon); 
y 
J 
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public void setPolygon(Polygon newValue) ( 
polygon = newValue; 
repaint(); 


. 


public Polygon getPolygon() ( 

Polygon returnValue; 
if (polygon.npoints == 0) ( 

returnValue = new Polygon(); 
j else £ 

returnValue = new Polygon( 

polygon.xpoints, polygon.ypoints, polygon.npoints); 

h 
return returnValue; 


J 


protected void paintComponent (Graphics g) ( 
super .paintComponent (g); 
g-drawPolygon(polygon) ; 

J 


public static void main(String args[]) ( 
Runnable runner = new Runnable() 4 
public void run() £ 
JFrame frame = new JFrame("Drawing Sample2"); 
frame.setDefaultCloseOperation(JFrame.EXIT_ON CLOSE); 
UndoableDrawingPanel2 drawingPanel = new UndoableDrawingPanel2(); 


UndoManager manager = new UndoManager(); 
drawingPanel.addUndoableEditListener(manager); 


JToolBar toolbar = new JToolBar(); 
JButton undoButton = 

new JButton(UndoManagerHelper.getUndoAction(manager)); 
toolbar.add(undoButton); 
JButton redoButton = 

new JButton(UndoManagerHelper.getRedoAction(manager)); 
toolbar.add(redoButton); 


frame.add(toolbar, BorderLayout.NORTH); 
frame.add(drawingPanel, BorderLayout.CENTER); 
frame.setSize(300, 150); 
frame.setVisible(true); 


$; 
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EventQueue.invokeLater(runner); 


J 
J 


Summary 


This chapter took both a short look and a long look at the Undo Framework found in the 
javax.swing.undo package with support from javax.swing.event. You saw how the framework 
support arrives already built in to the Swing text components. In addition, you learned how to 
build support into your own classes. With the interfaces and classes found in the Undo Framework, 
you can make any editable object support both undo and redo capabilities. 

The next chapter introduces the accessibility support for the Swing component set. There, 
you'll learn about the support for using assistive technologies with the components and 
working with audio cues. 


CHAPTER 22 


Accessibility 


A standard part of the Swing framework is support for assistive technologies. These technologies 
allow your Swing-based programs to be accessible to those with physical challenges. Some 
users need screen readers, audio cues, or just an input mode that doesn't require the mouse. 
Mouse-less input is typically through the keyboard, but it also could be through specialized 
input devices, such as those that are voice-activated. 

Users don't need to be physically challenged to take advantage of options you, as the 
developer, can use to make your programs more accessible. For example, you might add tooltip 
text, which users can see by resting their mouse over the component. Limited-vision users 
taking advantage of accessibility devices could rely on that text to describe the component with 
a screen reader. Other options include keyboard accelerators and menu mnemonics, which 


allow users to navigate around the screen and activate actions with minimal hand movement. 


This chapter offers some suggestions to help you create programs that follow federal 
guidelines in the United States, known as Section 508 Accessibility Requirements. For details 
on these requirements, refer to Accessibility for Everybody: Understanding the Section 508 
Accessibility Requirements, by John Paul Mueller (Apress, 2003; ISBN 1-59059-086-4). Sun also 
offers a resource at http://www. sun.com/access/background/laws . html, which includes references 
to international resources, as well as those in the United States. And, of course, there is the JFC 
Assistive Technologies home page, at http: //java.sun.com/products/jfc/accessibility/. 


Accessibility Classes 


The javax.accessibility package is both the most and least used package. Provided you 
configure your Swing components properly, everything happens behind the scenes. When a 
user taking advantage of an accessibility device runs the program, the Java Accessibility API 
steps in and provides the necessary information to the device. For instance, when creating an 
Imagelcon, there are two sets of constructors: those without a description argument and those 
with a description argument. 


// Without description argument 
public Imagelcon() 

public Imagelcon(Image image) 
public Imagelcon(String filename) 
public Imagelcon(URL location) 
public Imagelcon(byte imageData[]) 
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// With description argument 


public Imagelcon(Image image, String description) 
public Imagelcon(String filename, String description) 
public Imagelcon(URL location, String description) 
public Imagelcon(byte imageData[ ], String description) 


By creating an ImageIcon with a description, your program automatically becomes more 
accessible. In addition to creating the icon with a description argument to the constructor, 
you can also assign the text later by calling the setDescription() method. 

One important interface, Accessible, and an abstract class, AccessibleContext, provide 
the core framework for the Java Accessibility API. 


Accessible Interface 


For a Swing component to work within the accessibility framework, it must implement the 
Accessible interface. 


public interface Accessible ( 
// Property 
public AccessibleContext getAccessibleContext(); 


J 


As the interface definition shows, there is only one method, which gets the current 
AccessibleContext instance for the implementing class. All the standard AWT and Swing 
components implement the interface. Several internal aspects of components, like the system 
menu bar on the title pane of the JInternalFrame, also implement the Accessible interface. 


AccessibleContext Class 


While the Accessible interface is all that a component must implement, the work is actually done 
in the AccessibleContext instance that it returns. The returned context is practically another 
component. It maps the accessible properties to the properties ofthe component. For example, 
with the JLabel component, when you get its AccessibleContext, you are getting the concrete 
subclass known as AccessibleJLabel. This subclass maps JLabel properties, such as the accessi- 
bleName property to the text property. As shown in Table 22-1, the abstract class itselfis larger than 
the interface. 


Table 22-1. AccessibleContext Properties 


Property Name Data Type Access 
accessibleAction AccessibleAction Read-only 
accessibleChildrenCount int Read-only 
accessibleComponent AccessibleComponent Read-only 
accessibleDescription String Read-write bound 


accessibleEditableText AccessibleEditableText Read-only 
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Table 22-1. AccessibleContext Properties (Continued) 


Property Name Data Type Access 
accessiblelcon Accessiblelcon Read-only 
accessibleIndexInParent int Read-only 
accessibleName String Read-write bound 
accessibleParent Accessible Read-write 
accessibleRelationSet AccessibleRelationSet Read-only 
accessibleRole AccessibleRole Read-only 
accessibleSelection AccessibleSelection Read-only 
accessibleStateSet AccessibleStateSet Read-only 
accessibleTable AccessibleTable Read-only 
accessibleText AccessibleText Read-only 
accessibleValue AccessibleValue Read-only 
locale Locale Read-only 


As Table 22-1 shows, there are several other classes found in the javax.accessibility 
package. However, typically, you don't need to worry about them, provided that you create 
your components and screens to be accessible. 


Creating Accessible Components 


This section presents some hints to help you create applications that will be accessible when 
used with assistive technologies. This is not meant to be an exhaustive list, but it does provide 
an overview of some helpful techniques. 


+ Asafirsttask, try to use your program without a mouse. Do your menus support accelerators 


and mnemonics? Do your buttons have mnemonics associated with them? Do your text 
fields have labels associated with them via the setLabelFor() method, and does each 
label have a mnemonic? 


Make sure your components have a short string associated with them. Ifa component, 
such as an image-only button, doesn't have a string, call the setAccessibleName() method 
ofthe AccessibleContext. Remember to localize this name if your program is targeting 
an internationalized audience. 


Work with tooltip text wherever possible. Ifitis not appropriate to have tooltip text with 
a component, be sure to call setAccessibleDescription(). 


Are your custom components accessible? If you've subclassed JComponent, that class 
doesn't implement the Accessible interface. But, if you've subclassed JPanel, it does. 
However, even though JPanel implements the interface, your component might not be 
providing the necessary accessibility information. Consider having your custom 
AccessibleContext extend JComponent.AccessibleJComponent when appropriate. 
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+ Components that are inside containers that aren't accessible are themselves not accessible. 
Be sure to use JPanel as your container, rather than the AWT Container class, to ensure 
your screens are accessible. 


Note To see how well you've done creating accessible programs, you can try using the Java Accessibility 
Utilities, available from the JFC Assistive Technologies home page at http: //java.sun.com/products/ 
jfc/accessibility/. These downloadable utilities are designed to let you see exposed accessibility 
properties in different forms. However, | personally couldn't get them to work. The jaccess. jar and 
jaccess-examples. jar files needed weren't available, nor were the imported classes for the code 
that was provided. 


Working with the Java Access Bridge 


If you happen to be working on a Microsoft Windows platform, you can try out the Java Access 
Bridge, available from http: //java.sun.com/products/accessbridge/. This utility is easy to use. 


Caution To get the Java Access Bridge, do not follow the link from the main Accessibility page. The link 
available there in early 2005 pointed to the 1.0.4 beta version of the product. You should download at least 
version 1.2, available directly from http: //java.sun.com/products/accessbridge/. 


After downloading accessbridge-1_2.zip, umpack it and run the Install program, found 
in the installer subdirectory. After the program checks Java virtual machines (JVMs) for 
compatibility, it prompts you to select in which of the compatible JVMs you want the bridge 
installed. As Figure 22-1 shows, ifyou happen to have a few JVMs on your system, this may be 
in several places. Just pick the ones you are most likely to use. The program might also prompt 
you to remove some of the older versions on your machine. The directories that begin with 
c:Aprogram filesijava are the different versions of Java Plug-in for the browser. 


Available Java virtual machines xi 


Java virtual machines found in cormmon places: 


cAprogram filesijavasoftjrey1.2bin 

cAprograrm filesijavasoftjreyl.3.1_02bin 

cAprograrm filesijavasoftjreyl.3.0_01ibin 

cAprograrm filesijavasoftjreyl.3.1_02bin 

cAprogram filestjavalj2re1.4.2 O6ibin al 


Install Search disks | Cancel | 


Figure 22-1. Installing the Java Access Bridge 
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After clicking the Install (or Install in All) button, you'll see a success window, as shown in 
Figure 22-2 (assuming everything succeeded). Installation is quick. 


Installation Completed xj 


Installation of the Java Access Bridge was successful, 


Figure 22-2. Java Access Bridge successfully installed 


Once you've installed the bridge, you can run programs like Java Monkey and Java Ferret 
(yes, those are their real names). Once running, these programs attach themselves to any Java 
programs that run through the same JVM. For instance, you can try running the tooltip sample 
program presented in Chapter 4 with Java Monkey, repeated here in Listing 22-1. 


Listing 22-1. Tooltip Sample 


import javax.swing.*; 
import java.awt.*; 


public class TooltipSample £ 


public static void main(String args[]) ( 
Runnable runner = new Runnable() £ 
public void run() £ 
JFrame frame = new JFrame("Tooltip Sample"); 
frame.setDefaultClose0peration(JFrame.EXIT_ON CLOSE); 


JPanel panel = new JPanel(); 
panel.setToo1TipText("<HtM1>Tooltip<br>Message"); 
frame.add(panel, BorderLayout.CENTER); 


JButton button = new JButton("Hello, World") £ 
public JToo1Tip createToo1Tip() ( 
JToo1Tip tip = super.createToolTip(); 
tip.setBackground(Color.YELLOW) ; 
tip.setForeground(Color.RED); 
return tip; 
) 
public boolean contains(int x, int y) [ 
if (x < 100) [ 
setToo1TipText("Got Green Eggs?"); 
j else £ 
setToolTipText("Got Ham?"); 
y 
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return super.contains(x, y); 


) 
E 
button.setToo1TipText("Hello, World"); 
frame.add(button, BorderLayout.NORTH); 


frame.setSize(300, 150); 
frame.setVisible(true); 
j 
5 
EventQueue.invokeLater(runner); 
) 
y 


You'll see the screen shown in Figure 22-3. If you don't immediately see the component 
tree, select the Refresh Tree option under the File menu in the Java Monkey window. 


Jalx 


File Panels 


=)- Tooltip Sample [frame] 
=)- [root pane] 
E- [panel] 
[panel] 
Hello, World [push button] 


Figure 22-3. Main Java Monkey screen 


Select the Accessibility API Panel option under the Panels menu to see the information 
available through the AccessibleContext, such as the name, description, and role. Figure 22-4 
shows an example. Be sure to scroll down to see all the available information. 


ml Java Accessibility API view 101 xf 
2 


Accessible Context information: 
Name: Hello, World 
Description: Got Ham? 
Role: push button 
Role in en_US locale: push button 
States: 
enabled,focusable,visible,showing,opaque 
States in en_US locale: 


Figure 22-4. Secondary Java Monkey screen 


The other program that comes with the Java Access Bridge is Java Ferret. This is more of a 
tracking program, where you can enable the tracking of different events, such as mouse, focus, and 
menu selection. Ifyou've enabled mouse tracking, you'll see the program updated. Figure 22-5 
shows an example ofthe Java Ferret information displayed when you move the mouse over the 
JButton in the sample tooltip program (Listing 22-1). 


Jolxi 


File UpdateSettings JavaEvents AccessibilityEwents 


Wersion Information: 
Java virtual machine version: 1.5.0 
Access Bridge Java class version: AccessBridge 1.2 G4 
Access Bridge Java DLL version: 1.2 
Access Bridge Windows DLL version: 1.2 GA, 


¡AccessibleContext information: [at (O, 0)] 
Name: Hello, Won 
Description: Got Ham? 
Role: push button 
Role in en_US locale: push button 
States: enabled focusable,visible,showing,opaque 
States in en_US locale: enabled, focusable, visible showing,opaque 
Index in parent: 1 
Children Count: O 
Bounding Rectangle: [4, 23, 296, 49] 
Parent's Name: 
¡Accessibleáctions info: 
Number of actions: 1 
Action O name: click 
¡Accessible Value information: 
Current alue: O 
Maximum Value: 1 
Minimum Yalue: O 


Figure 22-5. Java Ferret interface 


CHAPTER 22 ACCESSIBILITY 


Note Does anyone else find it ironic that the Java Monkey and Java Ferret programs are not themselves 


very accessible? Where are the mnemonics and menu accelerators? 


Summary 


This chapter explored how the Swing APIs help make your programs more accessible, both for 
the normal user and the physically challenged. By following the suggestions in this chapter, 
your programs should be well on their way to meeting federal and international guidelines. 
With the help of the Java Monkey and Ferret programs, you can discover if sufficient attributes 


are exposed to users needing the accessibility features. 


And this wraps up your tour of Swing. Be sure to visit The Swing Connection maintained 
by Sun at http: //www.theswingconnection.com/ to follow the latest happenings. 
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APPENDIX 


Ul Manager Properties 


uscio this book are tables that list the property names and data types for all the UlResource 
elements of specific Swing components. Although these tables show all the information about 
a specific component, itis handy to have the information about property names for all ofthe 
components in one place. 

With that in mind, this appendix provides a complete, alphabetical list of properties used 
by the predefined look and feel classes—Motif, Metal/Ocean, Windows, GTK, and Synth— 
provided with the Swing release for the Java 2 Platform Standard Edition, version 5.0 (J2SE 5.0). 
The table indicates with an Xwhich of the five look and feel classes uses a particular property. 
For properties defined within the base Basic look and feel, these are assumed to be used by 
all the look and feel types, since all ofthe system-defined look and feel classes extend from 
BasicLookAndFeel. Itis possible that a subclass masks the use ofa property defined for the Basic 
look and feel, and in fact doesn't physically use one flagged as such in the table. Also, since the 
GTK look and feel is a subclass of Synth, a similar situation arises with GTK, too. 

To change the default setting for any of these properties, you need to notify the UlManager 
by storing a new setting in the lookup table ofthe UIManager. For instance, to change the default 
text for the Yes button in a JOptionPane, you need to replace the OptionPane.yesButtonText property 
with the new setting (Si, in this example): 


UlManager.put("OptionPane.yesButtonText", "Si"); 


Then any component created after the setting change will get the new value: Si. If you 
want a displayed component to get the new setting, you must call its updateU1() method after 
changing the setting. 

When you change the current look and feel, any custom settings you install may be lost. If 
the class of the property value setting implements the UlResource interface (an empty marker 
interface such as Serializable), the setting will be replaced by the default setting ofthe look 
and feel. For example, the following setting would be saved when the look and feel changes: 


UlManager.put("OptionPane.background", Color.RED); 
Conversely, the following setting would not be saved when the look and feel changes: 
UlManager.put("OptionPane.background", new ColorUIResource(Color.RED)); 


If the property value setting does not implement the UIResource interface, the property 
setting is retained when the look and feel changes. 
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Note The specific set of available properties changes with each JFC/Project Swing release. The listing 
here reflects the current settings for J2SE 5.0. Some properties did not exist in earlier versions, and others 
may get replaced in later versions. The changes tend to be minor, but they do exist. 


UlResource Elements for the Predefined Look and Feel Classes 


Property String Object Type CDE/Motif Metal Windows  GTK Synth 
AbstractButton.clickText String XxX XxX Xx XxX x 
AbstractDocument.additionText String XxX XxX Xx XxX Xx 
AbstractDocument.deletionText String XxX Xx Xx XxX Xx 
AbstractDocument .redoText String XxX XxX XxX XxX Xx 
AbstractDocument.styleChangeText String XxX XxX Xx XxX Xx 
AbstractDocument .undoText String XxX XxX XxX Xx Xx 
AbstractUndoableEdit.redoText String XxX XxX Xx XxX Xx 
AbstractUndoableEdit.undoText String XxX XxX Xx Xx Xx 
activeCaption Color XxX Xx Xx XxX Xx 
activeCaptionBorder Color XxX XxX Xx XxX Xx 
activeCaptionText Color Xx Xx Xx Xx Xx 
Application.useSystemFontSettings Boolean XxX XxX 

ArrowButton.size Integer Xx Xx 
ArrowButtonUl String Xx XxX 
AuditoryCues.allAuditoryCues String Xx XxX Xx XxX x 
AuditoryCues.cueList String Xx Xx Xx Xx Xx 
AuditoryCues.defaultCueList String XxX 

AuditoryCues.noAuditoryCues String XxX XxX Xx XxX x 
AuditoryCues.playList String XxX XxX XxX XxX x 
black Color Xx 

Button. actionMap ActionMap Xx Xx XxX Xx Xx 
Button.background Color xX Xx XxX x 
Button.border Border Xx Xx Xx Xx Xx 
Button.contentAreaFilled Boolean Xx Xx 
Button. darkShadow Color Xx Xx x Xx Xx 
Button.dashedRectGapHeight Integer Xx 


Button.dashedRectGapWidth Integer XxX 
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UlResource Elements for the Predefined Look and Feel Classes (Continued) 


Property String 


B 
B 
B 
B 


uu 


B 
B 
B 
B 


B 


B 


C 


utton.defaul 
utton.disab] 
utton.disab] 
utton.disab] 


utton.disabl 


utton.dashedRectGapX 
utton.dashedRectGapY 
ltButtonFollowsFocus 


ledForeground 
ledGrayRange 
LedShadow 
ledText 


utton.disabl] 
ackground 


utton.focus 


utton.font 


utton.icon 


utton. light 


uttonUl 


aretColor 


ledToo1BarBorderw»> 


utton.focusInputMap 


utton.foreground 
utton.gradient 


utton.highlight 


utton.iconTextGap 


utton.margin 
utton.rollover 
utton.rolloverIconType 
utton.select 

utton. shadow 
utton.showMnemonics 
utton.textIconGap 
utton.textShiftOffset 


utton.toolBarBorderBackground 


CheckBox. background 


CheckBox. border 


CheckBox.darkShadow 


Object Type CDE/Motif 
Integer 

Integer 

Boolean Xx 
Color 

Integer[ ] 

Color 

Color 

Color 

Color 

InputMap Xx 
Font Xx 
Color XxX 
List 

Color XxX 
Icon 

Integer 

Color XxX 
Insets Xx 
Boolean Xx 
String 

Color XxX 
Color XxX 
Boolean 

Integer XxX 
Integer Xx 
Color 

String Xx 
Color 

Color Xx 
Border Xx 
Color 


Metal Windows 
Xx 
Xx 
Xx Xx 
Xx 
Xx 
Xx 
Xx 
Xx 
Xx Xx 
Xx Xx 
Xx Xx 
Xx Xx 
Xx 
Xx Xx 
Xx Xx 
Xx Xx 
Xx Xx 
Xx 
Xx 
Xx Xx 
Xx 
Xx Xx 
Xx Xx 
Xx 
Xx Xx 
Xx Xx 
Xx Xx 
Xx 


GTK 


A 


AS 
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Synth 


> 


IS 
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UlResource Elements for the Predefined Look and Feel Classes (Continued) 
CDE/Motif 


Property 
CheckBox 


CheckBox 
CheckBox 
CheckBox 
CheckBox 
CheckBox 
CheckBox 
CheckBox 
CheckBox 
CheckBox 
CheckBox 
CheckBox 
Checkbox 
CheckBox 
CheckBox 
CheckBox 
CheckBox 


CheckBox 
Foregrou 


CheckBox 
Selectio 


CheckBox 
CheckBox 
CheckBox 
CheckBox 
CheckBox 
CheckBox 
CheckBox 
CheckBox 


Fore ground 


CheckBox 
CheckBox 
CheckBox 


APPENDIX 


String 

.disabledText 
«focus 
«focusInputMap 
«font 

.Foreground 
.gradient 
«highlight 

. icon 
.interiorBackground 
«light 

.margin 

.Tollover 

«selecta 

«Shadow 
.textIconGap 
.textShiftOffset 
enuTtem.acceleratorFont 


enultem.accelerator w» 
nd 


enultem.accelerator w» 
nForeground 


enultem. actionMap 
enultem.arrowIcon 
enuTtem. background 
enulTtem. border 
enuTtem.borderPainted 
enuTtem.checkIcon 
enuTtem. commandSound 


enultem. disabled» 


enultem. font 


enuTtem. foreground 


enuTtem.gradient 
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Object Type 


Color 
Color 
InputMap 
Font 
Color 
List 
Color 
Icon 
Color 
Color 
Insets 
Boolean 
Color 
Color 
Integer 
Integer 
Font 


Color 
Color 


ActionMap 
Icon 
Color 
Border 
Boolean 
Icon 
String 


Color 


Font 
Color 


List 


AS 


SS 


SA AAA ASS > 


AS 


Metal 


SA AAA 


IS > 


SAA ASAS ASAS > 


> 


Windows 


AS ASAS > AS AS NS 


s »” 


GTK 


SS 


SAA ASAS ASA > 


AS 


Synth 


NS 


AS > 


AS 


UlResource Elements for the Predefined Look and Feel Classes (Continued) 


Property String 


CheckBoxMenultem. margin 


CheckBoxMenuTtem.opaque 


CheckBoxMenultem. selection w» 


Background 


CheckBoxMenultem. selection w» 


Foreground 


CheckBoxMenulTtemUI 


CheckBoxUI 


Col 
Col 
Col 
Col 
Col 
Col 
Col 


lorChooser. background 
lorChooser.cancelText 
lorChooser. font 
lorChooser.foreground 
lorChooser.hsbBlueText 
lorChooser.hsbBrightnessText 


lorChooser.hsbDisplayedw> 


MnemonicIndex 


Co] 
Co 
Col 
Col 
Col 
Col 
Col 
Col 


Col 
Col 
Co 
Col 


MnemonicIndex 


Co] 
Co] 
Co] 


lorChooser .hsbGreenText 


lorChooser.hsbHueText 


lorChooser. hsbMnemonic 
lorChooser.hsbNameText 
lorChooser.hsbRedText 
lorChooser.hsbSaturationText 
lorChooser.okText 


lorChooser.panels 


lorChooser.previenText 


lorChooser.resetMnemonic 


lorChooser.resetText 


lorChooser.rgbBlueDisplayedw» 


lorChooser.rgbBlueMnemonic 


lorChooser.rgbBlueText 


lorChooser.rgbDisplayedw> 


MnemonicIndex 


Object Type 


Insets 
Boolean 


Color 
Color 


String 
String 
Color 
String 
Font 
Color 
String 
String 
Integer 


String 
String 
Integer 
String 
String 
String 
String 


AbstractColorw 
ChooserPanel[ ] 


String 
Integer 
String 
Integer 


Integer 
String 
Integer 
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CDE/Motif 
Xx 


Xx 
Xx 


pe 


A ASA AAA ASAS ASAS 


SS 
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Metal 
Xx 


Xx 
Xx 


> 


AA 


SA AAA ASAS 


AS 


Windows 
Xx 


Xx 
Xx 


> 


AAA ASAS 


AAA ASAS 


NS 


GTK 


A A 


AA 


OS 


> 
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Synth 


> 


AA 


A 


AS 


AS 
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UlResource Elements for the Predefined Look and Feel Classes (Continued) 


Property String 


ColorChooser.rgbGreenDisplayed tw 
MnemonicIndex 


ColorChooser.rgbGreenMnemonic 
ColorChooser.rgbGreenText 
ColorChooser.rgbMnemonic 
ColorChooser.rgbNameText 


ColorChooser.rgbRedDisplayedw»> 
MnemonicIndex 


ColorChooser.rgbRedMnemonic 
ColorChooser.rgbRedText 
ColorChooser.sampleText 
ColorChooser.showPreviewPanelText 


ColorChooser.swatchesDefault w» 
RecentColor 


ColorChooser.swatchesDisplayed tw 
MnemonicIndex 


ColorChooser.swatchesMnemonic 
ColorChooser.swatchesNameText 


ColorChooser.swatchesRecent w» 
SwatchSize 


ColorChooser.swatchesRecentText 
ColorChooser.swatchesSwatchSize 
ColorChooseruI 

ComboBox. actionMap 
ComboBox.ancestorInputMap 
ComboBox. background 

ComboBox. border 
ComboBox.buttonBackground 
ComboBox. buttonDarkShadow 
ComboBox.buttonHighlight 
ComboBox. buttonShadow 

ComboBox. control 


ComboBox.controlForeground 


ComboBox.disabledBackground 


Object Type 


Integer 


nteger 
String 
nteger 
String 


Integer 


nteger 
String 
String 
Boolean 


Color 


Integer 


Integer 
String 


Dimension 


String 
Dimension 
String 
ActionMap 
InputMap 
Color 
Border 
Color 
Color 
Color 
Color 
Color 
Color 


Color 


CDE/Motif 


> OS 


AS 


ASAS ASAS AS AA Ass 


Metal 


> OS 


AS 


AS AAA ASAS Ass 


Windows 


> 


AAA ASA 


GTK 


OS SA >>>”) > 


> 


AS 


AS AAA ASA ASA 


> OS 


AS 


AAA AAA ASA ASA 
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UlResource Elements for the Predefined Look and Feel Classes (Continued) 


Property String Object Type CDE/Motif Metal Windows  GTK Synth 
ComboBox. font Font Xx Xx Xx Xx Xx 
ComboBox. foreground Color Xx XxX Xx Xx XxX 
ComboBox.rendererUselistColors Boolean Xx Xx 
ComboBox.selectionBackground Color Xx XxX Xx Xx XxX 
ComboBox.selectionForeground Color Xx XxX Xx Xx XxX 
ComboBox. showPopupOnNavigation Boolean Xx XxX Xx XxX XxX 
ComboBox.timeFactor Long Xx Xx Xx XxX Xx 
ComboBox.togglePopupText String Xx XxX Xx Xx XxX 
ComboBoxUI String Xx Xx Xx Xx Xx 
ComponentUul String XxX Xx XxX Xx Xx 
control Color Xx Xx Xx Xx Xx 
contro1DkShadow Color Xx Xx Xx Xx Xx 
controlHighlight Color Xx XxX Xx Xx Xx 
controlLightShadow Color Xx 

controlLtHighlight Color Xx Xx Xx Xx XxX 
controlShadow Color Xx Xx Xx Xx Xx 
controlText Color Xx Xx Xx Xx Xx 
dark Color Xx 
desktop Color Xx XxX Xx Xx XxX 
Desktop .ancestorInputMap InputMap Xx Xx Xx XxX Xx 
Desktop .background Color Xx XxX Xx Xx XxX 
Desktop .windowBindings Object[ ] ? Xx Xx Xx Xx Xx 
DesktopIcon.background Color XxX 

DesktopIcon.border Border Xx Xx Xx Xx XxX 
DesktopIcon. font Font XxX 

DesktopIcon.foreground Color Xx 

DesktopIcon.icon Icon Xx 

DesktopIcon.width Integer xXx Xx 
DesktopIcon.windowBindings Object[ ] € Xx 

DesktopIconUI String Xx Xx Xx Xx Xx 


pa 
> 
> 
>< 


DesktopPane.actionMap ActionMap 
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UlResource Elements for the Predefined Look and Feel Classes (Continued) 


Property String 

DesktopPaneUI 

DirectoryPaneUl 
EditorPane.actionMap 
EditorPane.background 
EditorPane.border 
EditorPane.caretAspectRatio 
EditorPane.caretBlinkRate 
EditorPane.caretForeground 
EditorPane.focusInputMap 
EditorPane. font 

EditorPane. foreground 
EditorPane.inactiveForeground 
EditorPane.keyBindings 
EditorPane.margin 
EditorPane.selectionBackground 
EditorPane.selectionForeground 
EditorPaneUlI 


FileChooser.acceptAllFilew» 
FilterText 


ileChooser.ancestorInputMap 


ileChooser.cancelButtonMnemonic 


ileChooser.cancelButtonText 


ileChooser.cancelButton ww 
ToolTipText 


ileChooser.deleteFileButtontw»> 
nemonic 


ileChooser.deleteFileButtonText 


FileChooser.deleteFileButton'w 
ToolTipText 


FileChooser.detailsViewButton tw» 
AccessibleName 


FileChooser.detailsViewButton tw» 
ToolTipText 


FileChooser.detailsViewIcon 


Object Type 
String 
String 
ActionMap 
Color 
Border 
Number 
Integer 
Color 
InputMap 
Font 

Color 
Color 
KeyBinding[ ] 
Insets 
Color 
Color 
String 
String 


InputMap 
Integer 
String 
String 


Integer 


String 
String 


String 


String 


Icon 


CDE/Motif 


ASAS ASAS Ass 


AS 


Metal 


ASAS ASA ASA 


AS 


Windows 
Xx 


pS 


A AAA 


AS 


GTK 


AAA ASAS AAA ASA ASAS Ass 


AS 


> 


AAA AAA ASA ASA 


AS 
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CDE/Motif 


Property String 


Fil 


Fil 


Mnemonic 


Fil 


Text 


Fil 


leChooser. 


leChooser. 


ToolTipText 


Fil 


leChooser. 


Mnemonic 


Fil 
Fil 
Fil 
Fil 
Fil 
Fil 


ileChooser. 
Text 


leChooser.. fi 


Mnemonic 


Fil 
Fi 
Fil 
Fil 
Fil 
Fil 
Fil 
Fil 
Fil 


leChooser.+fil 


leChooser.ho 


AccessibleName 


Fil 
Fil 
Fil 
Fil 
Fil 
Fil 


leChooser.ho 


leChooser.ho 


AccessibleName 


leChooser. fil 
leChooser. fil 
leChooser. fil 
leChooser. fil 


leChooser.+fil 


leChooser.+fil 


leChooser. fil 
leChooser. fol 
leChooser. fol 
leChooser.hel 
leChooser.hel 


leChooser.hel 


leChooser.directoryDescription w» 
Text 
leChooser.directory0penButton tw» 
directory0penButton w» 
directory0penButton w»> 
enterFileNameLabel tw» 


enterFileNameLabelw»> 


leDescriptionText 


eNameLabelMnemonic 
eNameLabelText 
esLabelMnemonic 
eslLabelText 
esOfTypeLabel w» 


esOfTypeLabelText 
terlabelMnemonic 
terlabelText 
dersLabelMnemonic 
dersLabelText 
pButtonMnemonic 
pButtonText 
pButtonToolTipText 


eFolder w» 


eFolderIcon 


eFolderToolTipText 


leChooser.listFont 
leChooser. listVienBackground 
leChooser .1istViewBorder 


leChooser .1istViewButton > 


Object Type 
String Xx 


Integer Xx 
String Xx 
String Xx 
Integer Xx 
String Xx 


String Xx 
Integer 
String 
Integer Xx 
String Xx 


Integer 


String 
Integer 
String 
String 
String 
Integer 
String 


A AAA 


String 
String 


Icon Xx 
String 

Font 

Color 

Border 


String 
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Metal 
Xx 


Xx 


AS 


eS 


Windows 
Xx 


Xx 


AS 


E 


GTK 


AS 
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Synth 
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UlResource Elements for the Predefined Look and Feel Classes (Continued) 


Property String Object Type CDE/Motif Metal Windows  GTK Synth 
ToolTipText 
FileChooser.listViewIcon Icon Xx Xx Xx Xx Xx 
FileChooser.listVienWindowsStyle Boolean Xx 
FileChooser.lookInLabelMnemonic Integer Xx 
FileChooser.lookInLabelText String Xx 
FileChooser.newFolderAccessiblew» String XxX 

ame 
Fi leChooser. newFolderButton'w> Integer Xx 

nemonic 
FileChooser.newFolderButtonText String Xx 
FileChooser.newFolderButtonTool tw» Xx 
TipText 
FileChooser.newFolderDialogText String Xx 
FileChooser.newFolderErrorw> String XxX XxX Xx Xx Xx 
Separator 
FileChooser.newFolderErrorText String XxX XxX Xx Xx Xx 
FileChooser.newFolderIcon Icon Xx Xx Xx Xx Xx 
FileChooser.newFolderToolTipText String Xx Xx 
FileChooser.openButtonMnemonic Integer XxX XxX XxX XxX x 
FileChooser.openButtonText String XxX Xx XxX XxX Xx 
FileChooser.openButtonToolTipText String Xx XxX Xx Xx Xx 
FileChooser.openDialogTitleText String Xx XxX Xx Xx Xx 
FileChooser.other.newFolder String XxX XxX Xx Xx x 
FileChooser.other.newFolder. String XxX XxX XxX XxX xXx 
subsequent 
FileChooser.pathLabelMnemonic Integer XxX x 
FileChooser.pathLabelText String XxX Xx 
FileChooser.readOnly Boolean XxX XxX Xx XxX Xx 
FileChooser. renameFileButton tw» Integer x 

nemonic 
FileChooser.renameFileButtonText String Xx 
FileChooser.renameFileButton tw» String Xx 
ToolTipText 
FileChooser.renameFileDialogText String Xx 
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UlResource Elements for the Predefined Look and Feel Classes (Continued) 
CDE/Motif 


Property String 


Fil 
Fil 
Fil 
Fil 
Fil 
Fil 
Fil 
Fil 
Fil 
Fil 


Text 


Fil 
Na 


Fil 
Fil 
Fil 
Fil 


leChooser.renameFileErrorText 


leChooser.renameFileErrorTitle 
leChooser. saveButtonMnemonic 
leChooser.saveButtonText 
leChooser.saveButtonToolTipText 
leChooser.saveDialogTitleText 
leChooser.saveInLabelText 
leChooser . updateButtonMnemonic 
leChooser . updateButtonText 


leChooser . updateButtonToo1Tip tw» 


leChooser .upFolderAccessiblew»> 
e 


leChooser .upFolderTcon 
leChooser.upFolderToo1TipText 
leChooser.usesSingleFilePane 


leChooser.useSystemExtension > 


Hiding 


Fil 
Fil 


leChooser .win32.newFolder 


leChooser .win32.newFolder. 


subsequent 


Fil 
Fil 
Fil 
Fil 
F 


pe 


Fil 


leChooserUI 
leView. computerIcon 
leView.directoryIcon 


leView. fileIcon 


leView. floppyDrivelcon 


leView. hardDrivelcon 


FormattedTextField.actionMap 


FormattedTextField.background 


FormattedTextField.border 


FormattedTextField.caret tw 


AspectRatio 


FormattedTextField.caretBlinkRate 


FormattedTextField.caretw 
Foreground 


Object Type 
String 
String 
Integer 
String 
String 
String 
String 
Integer 
String 
String 


String 


Icon 
String 
Boolean 


Boolean 


String 
String 


String 
Icon 

Icon 

Icon 

Icon 

Icon 
ActionMap 
Color 
Border 


Number 


Integer 


Color 


SS 


> 


>» 


AAA ASAS ASAS 


> 


Metal Windows 


AS > A 


AS 


AS AAA 


> 


AS > SI ASAS 


>» 


AS 


> 


GTK 


AS ASAS 


AA > 


>< 


823 


Synth 


Sa >” 


> 


AS 


AA 
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UlResource Elements for the Predefined Look and Feel Classes (Continued) 
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Property String 


For 
For 
For 


For 


For 


For 
For 


For 


For 


For 
For 
For 


For 


ne 


attedTextField. 
attedTextField. 
attedTextField. 


attedTextField. 
Background 


attedTextField. 
Foreground 


attedTextField. 
attedTextField. 


attedTextField. 
Background 


attedTextField. 
Foreground 


attedTextField 
View.browseFil 
View.resetButt 


View. submitBut 


onicIndex 
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focusInputMap 
font 
foreground 


inactivew» 


inactivew» 


keyBindings 
margin 


selection» 


selection» 


UI 
eButtonText 
onText 


tonText 


GTKColorChooserPanel. displayed tw 


GTKColorChooserPanel.mnemonic 


GTKColorChooserPanel.nameText 


inactiveCaption 


inactiveCaptionBorder 


inactiveCaptionText 


info 


infoText 


InternalFrame.acti 
InternalFrame. acti 


InternalFrame.acti 
Background 


InternalFrame.acti 
Foreground 


InternalFrame.acti 


InternalFrame.bord 


InternalFrame.bord 


onMap 
veBorderColor 


veTitlew» 


veTitlew» 


veTitleGradient 
er 


erColor 


Object Type 
InputMap 
Font 

Color 


Color 


Color 


KeyBinding[ ] 
Insets 


Color 


Color 


String 
String 
String 
String 
Integer 


Integer 
String 
Color 
Color 
Color 
Color 
Color 
ActionMap 
Color 


Color 


Color 


List 
Border 


Color 


CDE/Motif 
Xx 


Xx 
Xx 
Xx 


> 


> 


AS 


SA AAA ASAS 


Metal 
Xx 


Xx 
Xx 
Xx 


AS > 


SA ASAS AS 


Windows 
Xx 


Xx 
XxX 
XxX 


AS 


A 


>< 


GTK 


AS 


> 


OS 


A 


AS 
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Property String 


InternalFra 
InternalFra 
InternalFra 
InternalFra 
InternalFra 
InternalFra 
InternalFra 
InternalFra 
InternalFra 
InternalFra 
InternalFra 
InternalFra 


InternalFra 
Background 


InternalFra 
Foreground 


InternalFra 
Gradient 


InternalFra 
AtOrigin 


InternalFra 
InternalFra 
InternalFra 
InternalFra 
InternalFra 


InternalFra 
Background 


InternalFra 
InternalFra 
InternalFra 
InternalFra 
InternalFra 


InternalFra 


InternalFra 


e .borderDarkShadow 
e.borderHighlight 
e.borderLight 

e .borderShadow 

e .borderWidth 
e.closeButtonToolTip 
e.closelcon 
e.closeSound 

e. icon 
e.iconButtonToo1Tip 
e.iconifyIcon 
e.inactiveBorderColor 


e.inactiveTitlew» 


e.inactiveTitlew» 


e.inactiveTitlew» 


e.layoutTitlePanew> 


e.maxButtonToo1Tip 
e.maximizelcon 
e.maximizeSound 
e.menulcon 
e.minimizelcon 


e.minimizelcon'w 


e.minimizeSound 
e.optionDialogBorder 
e.paletteBorder 
e.paletteCloselcon 
e.paletteTitleHeight 
e.resizelconHighlight 


e.resizelconShadow 


Object Type 


Color 
Color 
Color 
Color 
Integer 
String 
Icon 
String 
Icon 
String 
Icon 
Color 


Color 
Color 
List 
Boolean 


String 
Icon 
String 
Icon 
Icon 


Color 


String 
Border 
Border 
Icon 
Integer 
Color 


Color 
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Metal 
Xx 


SA AAA ASAS 


OS 


OS 


Windows 


AAA AAA ASAS ASA Ass 


> 


GTK 


AS 


SSA AA 
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UlResource Elements for the Predefined Look and Feel Classes (Continued) 
Property String 


InternalFra 
ToolTip 


InternalFra 
InternalFra 
InternalFra 
InternalFra 
InternalFra 
InternalFra 
InternalFra 
InternalFra 


InternalFra 
ButtonAccess 


InternalFra 
ButtonText 


InternalFra 


InternalFra 


InternalFra 
iconifylcon 


InternalFra 
InternalFra 
InternalFra 
aximizelcon 


InternalFra 


InternalFra 
inimizelcon 


InternalFra 


InternalFra 


InternalFra 


sizeButtonText 


InternalFra 


InternalFra 


e.restoreButton'w» 


e. 


e. 


+ 


«ti 


+ 


z 


.restoreDownSound 
.restoreUpSound 
itleButtonHeight 
.titleButtonWidth 


tleFont 


itlePaneHeight 
useTaskBar 


indowBindings 


eTitlePane.closew» 
ibleName 


eTitlePane.closew» 


eTitlePane.closelcon 


eTitlePane. 
iconifyButtonAccessibleName 


eTitlePane. 


eTitlePane. 


aximizeButtonAccessibleName 


eTitlePane. 


aximizeButtonText 


eTitlePane. 


eTitlePane. 


inimizeButtonText 


eTitlePane. 


eTitlePane. 


oveButtonText 


eTitlePane. 
restoreButtonText 


eTitlePane. 


eTitlePane. 
titlePaneLayout 


eTitlePaneUuI 
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Object Type 
String 


String 
String 
Integer 
Integer 
Font 
Integer 
Boolean 
Object[ ] 4 
String 


String 


Icon 


String 
Icon 
String 
String 
Icon 
String 
Icon 
String 
String 
String 
LayoutManager 


String 


CDE/Motif 
Xx 


Xx 


Metal 
Xx 


Xx 


Windows 
Xx 


OS 


GTK 


Synth 
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UlResource Elements for the Predefined Look and Feel Classes (Continued) 


Property String Object Type CDE/Motif Metal Windows  GTK Synth 
InternalFrameUT Stig XX XX IX 
IsindexView. prompt String Xx Xx Xx XxX Xx 
Label. actionMap ActionMap Xx XxX Xx Xx XxX 
Label. background Color Xx XxX Xx Xx XxX 
Label. border Border Xx XxX Xx Xx XxX 
Label.disabledForeground Color Xx XxX Xx Xx XxX 
Label.disabledShadow Color Xx XxX Xx XxX XxX 
Label.font Font Xx XxX Xx Xx XxX 
Label. foreground Color Xx XxX Xx Xx XxX 
LabelUI String Xx XxX Xx Xx XxX 
light Color Xx 
List.actionMap ActionMap Xx Xx Xx XxX Xx 
List.background Color Xx XxX Xx XxX Xx 
List.border Border Xx Xx Xx Xx Xx 
List.cellHeight Integer Xx XxX 
List.cellRenderer ListCellw» Xx Xx Xx Xx Xx 
Renderer 
List.focusCellHighlightBorder Border Xx Xx Xx Xx XxX 
List.focusInputMap InputMap XxX Xx Xx XxX Xx 
List.focusInputMap.RightToLeft InputMap XxX Xx Xx XxX XxX 
List.font Font Xx Xx Xx Xx XxX 
List.foreground Color Xx Xx Xx Xx XxX 
List.lockToPosition0nScroll Boolean Xx x Xx Xx XxX 
List.rendererUselistColors Boolean Xx XxX 
List.rendererUseUIBorder Boolean Xx XxX 
List.selectionBackground Color Xx Xx Xx Xx Xx 
List.selectionForeground Color Xx Xx Xx Xx XxX 
List.timeFactor Long Xx Xx XxX Xx Xx 
Listul String Xx Xx Xx Xx Xx 
menu Color XxX Xx Xx XxX Xx 
enu.acceleratorDelimiter String Xx XxX 
enu.acceleratorFont Font XxX Xx Xx XxX Xx 
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UlResource Elements for the Predefined Look and Feel Classes (Continued) 


Property String 
enu.acceleratorForeground 


enu.acceleratorSelectiontw»> 
Foreground 


enu.actionMap 
enu.arrowIcon 
enu.background 
enu.border 
enu.borderPainted 
enu.checkIcon 
enu.crossMenuMnemonic 
enu.delay 
enu.disabledForeground 
enu. font 

enu. foreground 
enu.margin 
enu.menuPopupOffsetX 
enu.menuPopupOffsetY 
enu.opaque 
enu.selectionBackground 
enu.selectionForeground 
enu.shortcutKeys 

enu. submenuPopupOffsetX 
enu. submenuPopupOffsetY 
enu.textIconGap 


enu.useMenuBarBackground w»> 
ForTopLevel 


enuBar.actionMap 
enuBar .background 
enuBar.border 
enuBar.borderColor 
enuBar. darkShadow 


enuBar. font 


enuBar. foreground 


Object Type 


Color 


Color 


ActionMap 
Icon 
Color 
Border 
Boolean 
Icon 
Boolean 
Integer 
Color 
Font 
Color 
Insets 
Integer 
Integer 
Boolean 
Color 
Color 
int[ ] 
Integer 
Integer 
Integer 


Boolean 


ActionMap 
Color 
Border 
Color 
Color 
Font 


Color 


CDE/Motif 


SA ASAS 


AA 


Metal 


A 


AA 


> 


AS 


> 


Windows 


A 


AS 


GTK 


A 


AS 
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A 
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Property String 


enulte 
enulte 
enulte 


enulte 


enulte 
enulte 
enulte 
enulte 
enulte 
enulte 
enulte 
enulte 
enulte 
enulte 
enulte 
enulte 
enulte 
enulte 


enulte 


enulte 


enuBar. 
enuBar. 
enuBar. 


enuBar. 


gradient 
highlight 
shadow 


windowBindings 


enuBarul 


.acceleratorDelimiter 


.acceleratorFont 


.acceleratorForeground 


.acceleratorselectionw» 
Foreground 


.actionMap 
.arrowlcon 
«background 

«border 
.borderPainted 
.checkIcon 

. commandSound 
.disabledForeground 
«Font 

.Foreground 

.margin 

.Opaque 
.selectionBackground 
.selectionForeground 
.textIconGap 

UI 


menuPressedItemB 


menuPressedItemF 


menuText 


MenuUlI 


MetalTitlePane.closeMnemonic 


MetalTitlePane.closeTitle 


Object Type 
List 

Color 
Color 
Object[ ] € 
String 
String 
Font 

Color 


Color 


ActionMap 
Icon 
Color 
Border 
Boolean 
Icon 
String 
Color 
Font 
Color 
Insets 
Boolean 
Color 
Color 
Integer 
String 
Color 
Color 
Color 
String 
Integer 
String 
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UlResource Elements for the Predefined Look and Feel Classes (Continued) 


Property String Object Type CDE/Motif Metal Windows  GTK Synth 
etalTitlePane.iconifyTitle String Xx 
etalTitlePane.maximizeMnemonic Integer Xx 
etalTitlePane.maximizeTitle String Xx 
etalTitlePane.restoreMnemonic Integer XxX 
etalTitlePane.restoreTitle String Xx 

mid Color Xx 

OptionPane.actionMap ActionMap Xx Xx XxX Xx Xx 

OptionPane.background Color XxX XxX Xx XxX Xx 

OptionPane.border Border XxX XxX Xx Xx Xx 

OptionPane.buttonAreaBorder Border XxX XxX Xx XxX Xx 

OptionPane.buttonClickThreshhold Integer XxX Xx Xx XxX x 

OptionPane.buttonFont Font Xx Xx Xx Xx Xx 

OptionPane.button0rientation Integer Xx Xx Xx Xx Xx 

OptionPane.buttonPadding Integer Xx XxX Xx XxX Xx 

OptionPane.cancelButtonMnemonic String Xx Xx XxX Xx Xx 

OptionPane.cancelButtonText String Xx Xx XxX Xx Xx 

OptionPane.cancelIcon Icon Xx Xx Xx Xx Xx 

OptionPane.error tw» Color XxX 

Dialog.border.background 

OptionPane.error tw» Color XxX 

Dialog.titlePane.background 

OptionPane.error tw» Color XxX 

Dialog.titlePane.foreground 

OptionPane.error tw» Color Xx 

Dialog.titlePane.shadow 

OptionPane.errorIcon Icon Xx Xx XxX Xx Xx 

OptionPane.errorSound String XxX Xx Xx Xx Xx 

OptionPane. font Font XxX XxX XxX XxX Xx 

OptionPane. foreground Color Xx XxX XxX XxX xXx 

OptionPane.informationIcon Icon Xx Xx XxX Xx Xx 

OptionPane.informationSound String XxX Xx Xx XxX Xx 

OptionPane.inputDialogTitle String XxX XxX Xx Xx x 

OptionPane.isYesLast Boolean Xx Xx Xx Xx Xx 


UlResource Elements for the Predefined Look and Feel Classes (Continued) 


Property String 


OptionPane 


OptionPane. 
OptionPane. 
OptionPane. 
OptionPane. 
OptionPane. 
OptionPane. 
OptionPane. 
OptionPane. 
OptionPane. 
OptionPane. 


OptionPane. 


OptionPane 


border .background 


OptionPane 


titlePane.background 


OptionPane 


titlePane.foreground 


OptionPane 


.messageAnchor 
essageAreaBorder 
essageDialogTitle 
essageFont 


essageForeground 


inimumSize 
noButtonMnemonic 
noButtonText 
nolcon 
okButtonMnemonic 
okButtonText 
okIcon 


.questionDialog. 


.questionDialog. 


.questionDialog. 


.questionDialog. 


titlePane.shadow 


OptionPane 


OptionPane. 


OptionPane 
OptionPane 
OptionPane 
OptionPane 


OptionPane 


border .background 


OptionPane 


titlePane.background 


OptionPane 


titlePane.foreground 


OptionPane 


.questionIcon 


questionSound 
.sameSizeButtons 
.separatorPadding 
.setButtonMargin 
.titleText 


.warningDialog. 


.warningDialog. 


.warningDialog. 


.warningDialog. 


titlePane.shadow 


OptionPane 


.warninglcon 


Object Type 
Integer 
Border 
String 
Font 
Color 
Dimension 
String 
String 
Icon 
String 
String 
Icon 


Color 


Color 


Color 


Color 


Icon 
String 
Boolean 
Integer 
Boolean 
String 


Color 


Color 


Color 


Color 


Icon 
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UlResource Elements for the Predefined Look and Feel Classes (Continued) 


Property String 
ptionPane.warningSound 
ptionPane.windowBindings 
ptionPane.yesButtonMnemonic 
ptionPane.yesButtonText 


0 
0 
0 
0 
OptionPane.yesIcon 
0 


ptionPaneUI 

Panel .background 

Panel .border 

Panel. font 

Panel. foreground 

PanelUI 
PasswordField.actionMap 
PasswordField.background 
PasswordField.border 
PasswordField.caretAspectRatio 
PasswordField.caretBlinkRate 
PasswordField.caretForeground 


PasswordField.disabledBackground 


PasswordField.focusInputMap 
PasswordField. font 
PasswordField. foreground 
PasswordField.inactiveBackground 
PasswordField.inactiveForeground 
PasswordField.keyBindings 
PasswordField.margin 


PasswordField.selectionBackground 


PasswordField.selectionForeground 


PasswordFieldUl 
PopupMenu.actionMap 
PopupMenu.background 
PopupMenu.border 


PopupMenu. consumeEventOnClose 


Object Type 
String 
Object[ ] f 
String 
String 
Icon 
String 
Color 
Border 
Font 
Color 
String 
ActionMap 
Color 
Border 
Number 
Integer 
Color 
Color 
InputMap 
Font 
Color 
Color 
Color 
KeyBinding[ ] 
Insets 
Color 
Color 
String 
ActionMap 
Color 
Border 


Boolean 
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UlResource Elements for the Predefined Look and Feel Classes (Continued) 


Property String Object Type CDE/Motif Metal Windows  GTK Synth 
o o 
PopupMenu. foreground Color Xx XxX Xx XxX Xx 
PopupMenu. popupSound String Xx Xx Xx XxX Xx 
PopupMenu. selectedWindoww Object[ ] £ Xx Xx Xx Xx Xx 
InputMapBindings 

PopupMenu. selectedWindoww»> Object[ ] * Xx Xx Xx Xx Xx 
InputMapBindings.RightToLeft 

PopupMenuSeparatorUl String Xx Xx Xx XxX Xx 
PopupMenuUI String Xx Xx Xx Xx Xx 
ProgressBar .background Color Xx Xx Xx XxX XxX 
ProgressBar.border Border Xx Xx Xx XxX XxX 
ProgressBar.cellLength Integer Xx Xx Xx Xx XxX 
ProgressBar.cellSpacing Integer Xx Xx Xx Xx Xx 
ProgressBar.cycleTime Integer Xx Xx Xx XxX Xx 
ProgressBar.font Font Xx Xx Xx XxX Xx 
ProgressBar.foreground Color Xx Xx Xx XxX XxX 
ProgressBar.highlight Color Xx 
ProgressBar.horizontalSize Dimension Xx x Xx Xx Xx 
ProgressBar.repaintInterval Integer Xx Xx Xx XxX Xx 
ProgressBar.selectionBackground Color Xx Xx Xx Xx XxX 
ProgressBar.selectionForeground Color Xx Xx Xx XxX XxX 
ProgressBar.shadow Color Xx 
ProgressBar.verticalSize Dimension Xx Xx Xx Xx Xx 
ProgressBarul String XxX Xx Xx Xx Xx 
ProgressMonitor.progressText String Xx Xx Xx Xx Xx 
RadioButton. background Color Xx Xx Xx XxX XxX 
RadioButton.border Border Xx Xx Xx Xx Xx 
RadioButton.darkShadow Color Xx Xx Xx Xx Xx 
RadioButton.disabledText Color Xx 

RadioButton.focus Color Xx Xx Xx 
RadioButton.focusInputMap InputMap Xx Xx Xx XxX XxX 
RadioButton. font Font Xx Xx Xx Xx 
RadioButton.foreground Color Xx XxX Xx Xx XxX 
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UlResource Elements for the Predefined Look and Feel Classes (Continued) 
CDE/Motif 


Property String 


RadioButton. 
RadioButton. 
RadioButton. 
RadioButton. 
RadioButton. 
RadioButton. 
RadioButton. 
RadioButton. 
RadioButton. 
RadioButton. 


RadioButton. 
RadioButton 


acceleratorFont 


RadioButton 


gradient 
highlight 

icon 
interiorBackground 
light 

margin 

rollover 

select 

shadow 
textIconGap 
textShiftOffset 


enultem. 


enultem. 


accelerator Foreground 


RadioButton 


enultem. 


accelerator SelectionForeground 


RadioButton 
RadioButton 
RadioButton 
RadioButton 
RadioButton 
RadioButton 
RadioButton 
RadioButton 


disabledForeground 


RadioButton 
RadioButton 
RadioButton 
RadioButton 
RadioButton 
RadioButton 


selectionBackground 


RadioButton 


enultem. actionMap 
enuTtem.arrowIcon 
enuTtem. background 
enulTtem. border 
enulTtem.borderPainted 
enuTtem.checkIcon 
enuTtem. commandSound 


enultem. 


enuTtem. font 
enultem. foreground 
enultem.gradient 
enultem.margin 
enultem.opaque 


enultem. 


enultem. 


selectionForeground 


Ul MANAGER PROPERTIES 


Object Type 
List 
Color 
Icon 
Color 
Color 
Insets 
Boolean 
Color 
Color 
Integer 
Integer 
Font 


Color 
Color 


ActionMap 
Icon 
Color 
Border 
Boolean 
Icon 
String 


Color 


Font 
Color 
List 
Insets 
Boolean 


Color 


Color 
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UlResource Elements for the Predefined Look and Feel Classes (Continued) 


Property String Object Type CDE/Motif Metal Windows  GTK Synth 
RadioButtonMenuTtemUI String XX XX XX 
RadioButtonUI String Xx Xx Xx XxX Xx 
RootPane. actionMap ActionMap XxX Xx Xx Xx XxX 
RootPane.ancestorInputMap InputMap Xx Xx Xx XxX Xx 
RootPane.colorChooserDialogBorder Border XxX 

RootPane.defaultButton w»> Object[ ] i XxX XxX XxX XxX XxX 
WindowKeyBindings 

RootPane.errorDialogBorder Border XxX 
RootPane.fileChooserDialogBorder Border Xx 

RootPane. frameBorder Border Xx 
RootPane.informationDialogBorder Border XxX 

RootPane.plainDialogBorder Border XxX 
RootPane.questionDialogBorder Border XxX 
RootPane.warningDialogBorder Border XxX 

RootPaneUl String XxX Xx Xx Xx XxX 
scrollbar Color Xx Xx Xx Xx Xx 
ScrollBar.actionMap ActionMap Xx Xx Xx Xx XxX 
ScrollBar.allowsAbsolute tw» Boolean Xx Xx Xx Xx Xx 
Positioning 

ScrollBar.ancestorInputMap InputMap Xx XxX Xx Xx XxX 
ScrollBar.ancestorInputMap. InputMap Xx XxX Xx XxX 
RightToLeft 

ScrollBar .background Color Xx XxX Xx Xx 
ScrollBar.border Color Xx Xx Xx Xx Xx 
ScrollBar.darkShadow Color Xx 

ScrollBar.focusInputMap InputMap Xx Xx x Xx Xx 
ScrollBar.focusInputMap. InputMap Xx XxX Xx XxX 
RightToLeft 

ScrollBar.foreground Color Xx XxX Xx XxX XxX 
ScrollBar.gradient List Xx 

ScrollBar.highlight Color XxX 
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UlResource Elements for the Predefined Look and Feel Classes (Continued) 


Property String 
ScrollBar.maximumThumbSize 
ScrollBar.minimumThumbSize 
ScrollBar. shadow 
ScrollBar.squareButtons 
ScrollBar. thumb 
ScrollBar.thumbDarkShadow 
ScrollBar.thumbHeight 
ScrollBar.thumbHighlight 
Scroll1Bar.thumbShadow 
ScrollBar.track 
ScrollBar.trackForeground 
ScrollBar.trackHighlight 


ScrollBar.trackHighlightw»> 
Foreground 


ScrollBar .width 
Scrol1BarUI 
ScrollPane.actionMap 


ScrollPane.ancestorInputMap 


ScrollPane.ancestorInputMap. 


RightToLeft 
ScrollPane. background 
ScrollPane. border 
ScrollPane. font 
ScrollPane.foreground 


ScrollPane.viewportBorder 


ScrollPane.viewportBorderInsets 


ScrollPaneUul 
Separator.background 
Separator.foreground 
Separator.highlight] 
Separator.insets 
Separator.shadow* 


Separator.thickness 


Object Type 


Dimension 
Dimension 
Color 
Boolean 
Color 
Color 
Integer 
Color 
Color 
Color 
Color 
Color 


Color 


Integer 
String 
ActionMap 
InputMap 
InputMap 


Color 
Border 
Font 
Color 
Border 
Insets 
String 
Color 
Color 
Color 
Insets 
Color 


Integer 
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UlResource Elements for the Predefined Look and Feel Classes (Continued) 


Property String Object Type CDE/Motif Metal Windows  GTK Synth 
Separator UT Sig XX XX. IX 
Slider.actionMap ActionMap Xx XxX Xx XxX Xx 
Slider.altTrackColor Color XxX 

Slider.background Color Xx Xx Xx Xx XxX 
Slider.border Border Xx XxX XxX XxX 
Slider.darkShadow Color XxX 

Slider.focus Color Xx XxX XxX XxX XxX 
Slider. focusGradient List XxX 

Slider. focusInputMap InputMap Xx XxX Xx Xx XxX 
Slider.focusInputMap.RightToLeft  InputMap Xx Xx Xx Xx Xx 
Slider.focusInsets Insets Xx XxX XxX XxX XxX 
Slider. foreground Color Xx Xx Xx XxX XxX 
Slider.gradient List XxX 

Slider.highlight Color Xx XxX Xx XxX 
Slider.horizontalSize Dimension XxX XxX XxX XxX 
Slider.horizontalThumbIcon Icon XxX 

Slider.majorTickLength Integer XxX 

Slider.minimumHorizontalSize Dimension Xx XxX XxX XxX XxX 
Slider.minimumVerticalSize Dimension XxX XxX Xx XxX XxX 
Slider.paintThumbArrowShape Boolean Xx XxX Xx Xx XxX 
Slider.paintValue Boolean Xx XxX 
Slider. shadow Color XxX XxX XxX XxX XxX 
Slider. thumb Color XxX 

Slider.thumbHeight Integer Xx XxX 
Slider.thumbWidth Integer Xx XxX 
Slider.tickColor Color XxX XxX Xx XxX XxX 
Slider.trackBorder Border Xx XxX 
Slider.trackWidth Integer XxX 

Slider.verticalSize Dimension Xx XxX Xx XxX XxX 
Slider.verticalThumbIcon Icon XxX 

SliderUI String Xx XxX Xx Xx XxX 
Spinner.actionMap ActionMap Xx Xx Xx XxX 
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UlResource Elements for the Predefined Look and Feel Classes (Continued) 


Property String 
Spinner.ancestorInputMap 
Spinner.arrowButtonBorder 
Spinner.arrowButtonTnsets 
Spinner.arrowButtonSize 
Spinner.background 


Spinner .border 


Spinner.editorBorderPainted 
Spinner.font 
Spinner.foreground 
Spinnerul 
SplitPane.actionMap 


SplitPane.activeThumb 


un 


plitPane.ancestorInputMap 
SplitPane.background 
SplitPane.border 
SplitPane.centerOneTouchButtons 
SplitPane.darkShadow 


SplitPane.dividerFocusColor 


SplitPane.dividerSize 


1%4) 


plitPane.highlight 


un 


plitPane. leftButtonText 
SplitPane.oneTouchButtonOffset 
SplitPane.oneTouchButtonSize 
SplitPane.oneTouchButtonsOpaque 
SplitPane.oneTouchExpandable 
SplitPane.oneTouchOffset 


SplitPane.rightButtonText 
SplitPane. shadow 
SplitPane.size 


SplitPane.supportsOneTouchButtons 


un 


plitPaneDivider.border 


un 


plitPaneDivider.draggingColor 


Object Type 
InputMap 
Border 
Insets 
Dimension 
Color 
Border 
Boolean 
Font 
Color 
String 
ActionMap 
Color 
InputMap 
Color 
Border 
Boolean 
Color 
Color 
Integer 
Color 
String 
Integer 
Integer 
Boolean 
Boolean 
Integer 
String 
Color 
Integer 
Boolean 
Border 


Color 
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UlResource Elements for the Predefined Look and Feel Classes (Continued) 


Property String Object Type CDE/Motif Metal Windows  GTK Synth 
Size 

SplitPaneUI String Xx XxX Xx Xx XxX 
StandardDialogUI String Xx Xx Xx xX 
swing.boldMetal Boolean XxX 
swing.plaf.metal.controlFont Font XxX 

swing.plaf.metal.smallFont Font XxX 

swing.plaf.metal.systemFont Font Xx 

swing.plaf.metal.userFont Font Xx 

TabbedPane.actionMap ActionMap Xx Xx Xx Xx XxX 
TabbedPane.ancestorInputMap InputMap Xx XxX Xx XxX 
TabbedPane .background Color Xx XxX Xx XxX 
TabbedPane.borderHightlightColor Color XxX 

TabbedPane.contentAreaColor Color Xx Xx e XxX XxX 
TabbedPane.contentBorderInsets Insets Xx XxX Xx Xx XxX 
TabbedPane. contentOpaque Boolean Xx Xx Xx Xx XxX 
TabbedPane. darkShadow Color Xx XxX Xx Xx XxX 
TabbedPane. focus Color Xx Xx Xx Xx XxX 
TabbedPane.focusInputMap InputMap Xx XxX Xx XxX XxX 
TabbedPane. font Font Xx XxX Xx XxX XxX 
TabbedPane. foreground Color Xx Xx Xx Xx XxX 
TabbedPane.highlight Color y XxX Xx Xx XxX 
TabbedPane. light Color Xx XxX Xx Xx Xx 
TabbedPane. opaque Boolean Xx Xx Xx Xx XxX 
TabbedPane. selected Color Xx XxX Xx XxX XxX 
TabbedPane.selectedForeground Color Xx Xx Xx Xx XxX 
TabbedPane.selectedTabPadInsets Insets Xx XxX Xx Xx Xx 
TabbedPane.selectHighlight Color XxX 
TabbedPane.selectionFollowsFocus Boolean Xx Xx Xx Xx XxX 
TabbedPane. shadow Color Xx XxX Xx XxX XxX 
TabbedPane.tabAreaBackground Color Xx XxX Xx Xx XxX 
TabbedPane.tabArealnsets Insets Xx XxX Xx Xx XxX 
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UlResource Elements for the Predefined Look and Feel Classes (Continued) 


Property String 
TabbedPane.tabInsets 
TabbedPane.tabRun0verlay 
TabbedPane.tabsOpaque 
TabbedPane.tabsOverlapBorder 
TabbedPane.textIconGap 
TabbedPane.unselectedBackground 


TabbedPane.unselectedTab w» 
Background 


TabbedPane.unselectedTab w» 
Foreground 


TabbedPane.unselectedTabHighlight 
TabbedPane. unselectedTabShadow 
TabbedPaneUl 

Table.actionMap 
Table.ancestorInputMap 


Table.ancestorInputMap. 
RightToLeft 


Table.background 
Table.darkShadow 
Table.focusCellBackground 
Table.focusCellForeground 
Table.focusCellHighlightBorder 
Table.font 

Table.foreground 
Table.gridColor 
Table.highlight 

Table. light 
Table.rendererUseTableColors 
Table.rendererUseUIBorder 
Table.rowHeight 
Table.scrollPaneBorder 
Table.selectionBackground 


Table.selectionForeground 


Object Type 
Insets 
Integer 
Boolean 
Boolean 
Integer 
Color 


Color 
Color 


Color 
Color 
String 
ActionMap 
InputMap 
InputMap 


Color 
Color 
Color 
Color 
Border 
Font 
Color 
Color 
Color 
Color 
Boolean 
Boolean 
Integer 
Border 
Color 


Color 


CDE/Motif 
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UlResource Elements for the Predefined Look and Feel Classes (Continued) 
CDE/Motif 


Property String 


TableUI 
text 


TextArea 
TextArea 
TextArea 


TextArea 


TextFiel 
TextFiel 
TextFiel 
TextFiel 
TextFiel 
TextFiel 
TextFiel 


TextFiel 


TextFiel 


TextArea. 
TextArea. 
TextArea. 
TextArea. 
TextArea. 
TextArea. 
TextArea. 


TextArea. 


Table.shadow 
TableHeader.background 
TableHeader.cellBorder 
TableHeader. font 
TableHeader. foreground 


TableHeaderul 


actionMap 
background 
border 
caretAspectRatio 
caretBlinkRate 
caretForeground 
focusInputMap 
font 


.Foreground 


.inactiveForeground 


.KeyBindings 


.margin 


TextArea. 


TextArea. 


d 


d 
d 
d 
d 
d 
d 
d 
d 


selectionBackground 


selectionForeground 


TextAreaUI 


.actionMap 
«background 

.border 
.CaretAspectRatio 
.CaretBlinkRate 
.CaretForeground 
.darkShadow 
.disabledBackground 
«FocusInputMap 


Object Type 


Color 
Color 
Border 
Font 
Color 
String 
String 
Color 
ActionMap 
Color 
Border 
Number 
Integer 
Color 
InputMap 
Font 
Color 
Color 
KeyBindingl[ ] 
Insets 
Color 
Color 
String 
ActionMap 
Color 
Border 
Number 
Integer 
Color 
Color 
Color 


InputMap 
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UlResource Elements for the Predefined Look and Feel Classes (Continued) 


Property String Object Type CDE/Motif Metal Windows  GTK 
TextField. font Font Xx Xx Xx 
TextField.foreground Color XxX XxX XxX XxX 
TextField.highlight Color XxX XxX Xx XxX 
TextField.inactiveBackground Color Xx XxX Xx Xx 
TextField.inactiveForeground Color Xx XxX Xx Xx 
TextField.keyBindings KeyBinding[ ]  X Xx Xx Xx 
TextField. light Color XxX Xx XxX XxX 
TextField.margin Insets XxX XxX Xx XxX 
TextField.selectionBackground Color XxX XxX Xx XxX 
TextField.selectionForeground Color XxX XxX Xx Xx 
TextField. shadow Color Xx Xx Xx Xx 
TextFieldUlI String XxX Xx Xx XxX 
textHighlight Color XxX XxX XxX Xx 
textHighlightText Color XxX XxX Xx XxX 
textInactiveText Color Xx Xx Xx Xx 
TextPane.actionMap ActionMap Xx Xx XxX Xx 
TextPane.background Color XxX XxX Xx XxX 
TextPane. border Border Xx Xx Xx Xx 
TextPane.caretAspectRatio Number Xx 
TextPane.caretBlinkRate Integer XxX XxX Xx XxX 
TextPane.caretForeground Color XxX Xx Xx Xx 
TextPane.focusInputMap InputMap Xx Xx XxX Xx 
TextPane. font Font Xx Xx x Xx 
TextPane.foreground Color XxX XxX Xx Xx 
TextPane.inactiveForeground Color XxX XxX Xx XxX 
TextPane.keyBindings KeyBinding[ ]  X Xx Xx Xx 
TextPane.margin Insets Xx Xx XxX Xx 
TextPane.selectionBackground Color XxX XxX XxX XxX 
TextPane.selectionForeground Color XxX XxX XxX Xx 
TextPaneUI String Xx Xx Xx XxX 
textText Color Xx Xx Xx Xx 
TitledBorder.border Border Xx Xx Xx Xx 
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UlResource Elements for the Predefined Look and Feel Classes (Continued) 


Property String Object Type CDE/Motif Metal Windows  GTK Synth 
TitledBorder font PR XXX IX 
TitledBorder.titleColor Color Xx Xx Xx Xx Xx 
ToggleButton.background Color Xx XxX Xx Xx XxX 
ToggleButton. border Border Xx XxX Xx Xx XxX 
ToggleButton.darkShadow Color Xx XxX Xx Xx XxX 
ToggleButton.disabledText Color XxX 

ToggleButton.focus Color XxX xXx 
ToggleButton.focusInputMap InputMap Xx XxX Xx XxX 
ToggleButton. font Font Xx XxX Xx XxX 
ToggleButton.foreground Color Xx Xx Xx Xx XxX 
ToggleButton.gradient List Xx 

ToggleButton.highlight Color Xx Xx Xx XxX XxX 
ToggleButton. light Color Xx XxX Xx XxX 
ToggleButton.margin Insets Xx Xx Xx y Xx 
ToggleButton. select Color Xx Xx 

ToggleButton. shadow Color Xx Xx Xx Xx XxX 
ToggleButton.textIconGap Integer Xx Xx Xx XxX Xx 
ToggleButton.textShiftOffset Integer Xx XxX Xx XxX Xx 
ToggleButtonUI String Xx Xx Xx XxX Xx 
ToolBar.actionMap ActionMap Xx Xx Xx Xx Xx 
ToolBar.ancestorInputMap InputMap Xx Xx Xx XxX Xx 
ToolBar.background Color Xx XxX Xx Xx XxX 
ToolBar.border Border Xx Xx Xx Xx Xx 
ToolBar.borderColor Color Xx 

Tool1Bar.darkShadow Color Xx Xx Xx Xx Xx 
ToolBar.dockingBackground Color Xx XxX Xx Xx XxX 
ToolBar.dockingForeground Color Xx XxX Xx Xx XxX 
ToolBar.floatingBackground Color Xx XxX Xx XxX XxX 
ToolBar.floatingForeground Color Xx XxX Xx XxX Xx 
ToolBar. font Font Xx Xx Xx Xx Xx 
ToolBar.foreground Color Xx XxX Xx Xx XxX 
ToolBar.handlelcon Icon Xx Xx 
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Property String 
ToolBar.highlight 


ToolBar.isRollover 


ToolBar.light 


ToolBar.nonrolloverBorder 


ToolBar.rolloverBorder 


ToolBar.separatorSize 


ToolBar.shadow 


ToolBarSeparatorUl 


Tool1Barul 


Too1Tip.background 


ToolTip.backgroundInactive 


Tool1Tip.border 


ToolTip.borderInactive 


Tool1Tip. font 


Too1Tip.foreground 


ToolTip.foregroundInactive 


ToolTip.hideAccelerator 


Too1TipUI 


Tree. 


Tree 


Tree. 
Tree. 
Tree. 


Tree. 


Tree 


Tree. 
Tree. 
Tree. 
Tree. 


Tree. 


Tree 


Tree 


actionMap 


.ancestorInputMap 


background 
changeSelectionWithFocus 
closedIcon 


collapsedIcon 


.drawDashedFocusIndicator 


drawHorizontalLines 
drawsFocusBorderAroundIcon 
drawVerticallines 
editorBorder 


editorBorderSelectionColor 


.expandedIcon 


.expanderSize 


Object Type 


Color 
Boolean 
Color 
Border 
Border 
Dimension 
Color 
String 
String 
Color 
Color 
Border 
Color 
Font 
Color 
Color 
Boolean 
String 
ActionMap 
InputMap 
Color 
Boolean 
Icon 
Icon 
Boolean 
Boolean 
Boolean 
Boolean 
Border 
Color 
Icon 


Integer 
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UlResource Elements for the Predefined Look and Feel Classes (Continued) 


Property String 


Tree 


Tree 


Tree 


Tree 


Tree 


Tree 


Tree. 


Tree. 


Tree. 
Tree. 
Tree. 
Tree. 
Tree. 


Tree. 


Tree. 


Tree. 


Tree. 


Tree. 


Tree. 


Tree. 


Tree. 
Tree. 


Tree. 


Tree. 


Tree. 


Tree. 


focusInputMap 


Tree.focusInputMap.RightToLeft 


font 
foreground 
hash 
iconBackground 
iconForeground 
iconHighlight 
iconShadow 


leafIcon 


.leftChildIndent 


line 


lineTypeDashed 


.openIcon 


padding 


paintLines 


rendererUseTreeColors 


.rightChildIndent 


ronHeight 


Tree.scrollsHorizontally w»> 
AndVertically 


scrol1sOnExpand 


selectionBackground 
selectionBorderColor 


.selectionForeground 


showsRootHandles 


textBackground 


.textForeground 


timeFactor 


TreeUl 


Viewport.background 


Viemport.font 


Object Type 
InputMap 
InputMap 
Font 

Color 
Color 
Color 
Color 


Color 


Color 
Icon 
Integer 
Color 
Boolean 
Icon 
Integer 
Boolean 
Boolean 
Integer 
Integer 


Boolean 


Boolean 
Color 
Color 
Color 
Boolean 


Color 


Color 
Integer 
String 
Color 


Font 
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UlResource Elements for the Predefined Look and Feel Classes (Continued) 


Property String Object Type CDE/Motif Metal Windows  GTK Synth 
Viemport..foregroand dar XX XX 
ViewportUul String Xx Xx Xx Xx Xx 
white Color xXx 
win.ansiVar.font.height Integer Xx Xx 

win.frame.captionFont. height Integer XxX Xx 

win.menu.font.height Integer Xx Xx 

win.tooltip.font.height Integer Xx XxX 

window Color XxX Xx Xx xX x 
windowBorder Color XxX XxX Xx XxX x 
windowText Color Xx Xx Xx Xx Xx 


a. Lowercase “b” is correct. 

b. Flattened ComponentInputMap pieces. Describes the 
the KeyStroke as specified in KeyStroke. getKeyStro 
Object used to determine the associated Action in a: 

c. Flattened Component InputMap pieces. Describes the 
the KeyStroke as specified in KeyStroke. getKeyStro 
Object used to determine the associated Action in a 

d. Flattened Component InputMap pieces. Describes the 
the KeyStroke as specified in KeyStroke. getKeyStro 
Object used to determine the associated Action in a 

e. Flattened Component InputMap pieces. Describes the InputMap, with every even number item being a String giving 
the KeyStroke as specified in KeyStroke.getKeyStroke(String) (or a KeyStroke), and every odd number item the 


nputMap, with every even number item being a String giving 
e 
n 
n 
e 
n 
n 
e 
n 
n 
e 
Object used to determine the associated Action in an ActionMap. 
n 
e 
n 
n 
e 
n 
n 
e 
n 
n 


String) (or a KeyStroke), and every odd number item the 
ActionMap. 
putMap, with every even number item being a String giving 
String) (or a KeyStroke), and every odd number item the 
ActionMap. 
putMap, with every even number item being a String giving 
String) (or a KeyStroke), and every odd number item the 
ActionMap. 


f. Flattened Component InputMap pieces. Describes the InputMap, with every even number item being a String giving 
the KeyStroke as specified in KeyStroke.getKeyStroke(String) (or a KeyStroke), and every odd number item the 
Object used to determine the associated Action in an ActionMap. 

g. Flattened ComponentInputMap pieces. Describes the InputMap, with every even number item being a String giving 
the KeyStroke as specified in KeyStroke.getKeyStroke(String) (or a KeyStroke), and every odd number item the 
Object used to determine the associated Action in an ActionMap. 

h. Flattened Component InputMap pieces. Describes the InputMap, with every even number item being a String giving 
the KeyStroke as specified in KeyStroke.getKeyStroke(String) (or a KeyStroke), and every odd number item the 
Object used to determine the associated Action in an ActionMap. 

i. Flattened Component InputMap pieces. Describes the InputMap, with every even number item being a String giving 

the KeyStroke as specified in KeyStroke.getKeyStroke(String) (or a KeyStroke), and every odd number item the 

Object used to determine the associated Action in an ActionMap. 

Deprecated, do not use. Property still set and available though. 

k. Deprecated, do not use. Property still set and available though. 


=. 
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A 
AbstractAction class, 170 
default implementation of Action 
interface, 38 
lookup property keys, 41 
properties, 41 
Swing-specific event handling, 37 
TextAction class as extension of, 535 
using actions, 38-41 
AbstractBorder class 
creating, 216 
extending to create borders, 232 
implements Border interface, 212 
javax.swing.border package, 216 
methods, 217 
AbstractButton class 
as parent class, 64 
ButtonModel interface, 99 
components grouped into ButtonGroup 
class, 115 
DefaultButtonModel interface, 99 
handling events, 102 
icons, 102 
internal positioning, 102 
mnemonics, 101 
parent class to JButton class, 67 
properties, 98 
AbstractCellEditor class, 623, 676 
creating CheckBoxNodeEditor class 
653-658 
managing CellEditorListener objects, 653 
AbstractColorChooserPanel class, 301 
getDefaultChooserPanels() method, 320 
implementing methods, 313 
installChooserPanel() method, 312 
represented by tabs in upper part of 
JColorChooser, 310 
subclassing, 311 
AbstractDocument class, 521 
attaching DocumentFilter to, 538 
introduction, 540 


PlainDocument class as specific 
implementation of, 541 
properties, 540 
setDocumentFilter() method, 542 
AbstractDocument.Content class 
implementations, 596 
AbstractFormatter class 
as mask for formatted text, 566 
AbstractFormatterFactory class, 566 
as mask for formatted text, 566 
AbstractLayoutCache class 
implements RowMapper interface, 670 
AbstractListModel class, 451 
extended by DefaultComboBoxModel 
class, 460 
introduction, 452 
subclassing, 462 
AbstractSpinnerModel class 
AbstractSpinnerModel class 
implements, 514 
introduction, 513 
SpinnerListModel class implements, 513 
SpinnerNumberModel class 
implements, 513 
AbstractTableModel class 
data storage, 676 
enabling default table cell renderers, 
694-695 
introduction, 691, 692 
specifying fixed JTable columns, 692-694 
AbstractUndoableEdit class, 783, 788 
subclassing, 798 
UlTResource Elements, 791 
Abstract Window Toolkit (AWT), 1 
accelerator property 
JMenu class, 171 
JMenultem class, 164 
acceleratorForeground property 
MetalLookAndFeel class, 772 
accelerators, 46 


847 


848 


INDEX 


acceleratorSelectedForeground property 

MetalLookAndrFeel class, 772 
accept() method 

filechooser class, 331 
acceptAllFileFilter property 

JFileChooser class, 327 
acceptAllFileFilterUsed property 

JFileChooser class, 327 
accessibility, 805 

classes, 805, 806 

Accessible interface, 806 
AccessibleContext class, 806 

creating accessible components, 807 

Java Access Bridge, 808-810 
accessibility classes 

javax.accessibility package, 805 
Accessible interface, 806 

implementation of, 807 
accessibleAction property 

AccessibleContext class, 806 
accessibleChildrenCount property 

AccessibleContext class, 806 
accessibleComponent property 

AccessibleContext class, 806 
AccessibleContext class 

extending JComponent. 

AccessibleJComponent, 807 

introduction, 806 

setAccessibleDescription() method, 807 
accessibleContext property 

Box class, 379 

JButton class, 105 

JCheckBox class, 127 

JCheckBoxMenultem component, 185 

JColorChooser class, 307 

JComboBox class, 492 

JComponent class, 79 

JDesktopPane component, 263 

JDialog class, 250 

JEditorPane class, 575 

JFileChooser class, 327 

JFrame class, 243 

JInternalFrame class, 254 

JLabel class, 89 

JLayeredPane class, 242 

JList class, 464 

JMenu class, 171 

JMenuBar class, 159 

JMenultem class, 164 


JOptionPane class, 281 
JPasswordField class, 564 
JPopupMenu class, 179 
JProgressBar component, 440 
JRadioButton class, 136 


JRadioButtonMenultem component, 191 


JRootPane class, 237 
JScrollBar component, 426 
JScrollPane class, 407 
JSeparator class, 175 
JSlider component, 431 
JSpinner class, 510 
JSplitPane class, 385 
JTabbedPane class, 399 
JTable class, 681 
JTableHeader class, 716 
JTextArea class, 571 
JTextComponent class, 523 
JTextField class, 529 
JToggleButton class, 120 
JToolBar class, 203 
JToolTip class, 85 
JTree class, 628 
JViewport class, 412 
JWindow class, 248 
ProgressMonitor class, 296 
accessibleDescription property 
AccessibleContext class, 806 
accessibleEditableText property 
AccessibleContext class, 806 
accessiblelcon property 
AccessibleContext class, 807 
accessiblelndexInParent property 
AccessibleContext class, 807 
AccessibleJLabel class 
JLabel class, 806 
accessibleName property 
AccessibleContext class, 807 
AccessibleJLabel class, 806 
accessibleParent property 
AccessibleContext class, 807 
accessibleRelationSet property 
AccessibleContext class, 807 
accessibleRole property 
AccessibleContext class, 807 
accessibleSelection property 
AccessibleContext class, 807 
accessibleStateSet property 
AccessibleContext class, 807 


accessibleTable property 
AccessibleContext class, 807 
accessibleText property 
AccessibleContext class, 807 
accessibleValue property 
AccessibleContext class, 807 
accessory property 
JFileChooser class, 327 
Action interface 
as extension of the ActionListener 
interface, 37, 170 
definition, 37 
Swing-specific event handling, 37 
Action objects 
adding to JMenuBar class, 589 
Swing text components come with, 585 
action property 
AbstractButton class, 98 
JComboBox class, 492 
JTextField class, 529 
actionCommand property 
AbstractButton class, 98 
DefaultButtonModel interface, 100 
JButton class, 107 
JComboBox class, 492 
JTextField class, 529, 557 
ActionEvent event 
JButton class, 107 
ActionFocusMover class 
programmatically moving focus, 49 
ActionListener interface 
AbstractButton class, 102 
Action interface is extension of, 37, 170 
adding to JFileChooser class, 324, 325 
creating, 19 
creating to handle input focus, 48 
customizing for JColorChooser class, 
305-307 
focusNextComponent( method, 48 
handling JCheckBox selection events, 130 
handling JCheckBoxMenultem selection 
events with ItemListener, 186 
handling JRadioButton selection events, 
139, 140 
handling JRadioButtonMenultem 
selection events, 190, 192 
handling JToggleButton selection 
events, 121 
listening to JComboBox events, 493-496 


INDEX 


listening to JMenultem events, 166 

listening to JTextField events, 556 
actionListeners property 

AbstractButton class, 98 

JComboBox class, 492 

JTextField class, 529 

Timer class, 36 
ActionMap class 

InputMagp class, 37 

Keymap interface, 554 

sharing instances to share actions, 44 
actionMap property 

JComponent class, 41, 79 
actionPerformed() method, 21 
actions property 

JFormattedTextField class, 567 

JTextComponent class, 523, 535 

JTextField class, 529 
ActiveValue class, 755 

constructing JLabel components, 757 
activeWindow property 

KeyboardFocusManager class, 55 
add() method 

ButtonGroup class, 117 

Container class, 157, 381, 397 

DefaultListModel class, 453 

DefaultMutableTreeNode interface, 662 

JMenu class, 169 

JMenuBar class, 158 

JPopupMenu class, 177 

JToolBar class, 203 
addActionForKeyStroke() method 

Keymap interface, 45 
addActionListener() method 

JButton class, 20 
addAuxiliaryLookAndFeel() method 

UlManager class, 776 
addCellEditorListener() method 

CellEditor interface, 654 
addChoosableFileFilter() method 

JFileChooser class, 330 
addChooserPanel() method 

JColorChooser class, 314 
addComponent() method 

Seven-Button GridBagLayout example, 352 
addCustomEntriesToTable() method 

MetalLookAndrFeel class, 774 
addEdit() method 

CompoundEdit class, 791 

UndoManager class, 792 
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addElement() method 
DefaultListModel class, 453 
addLayoutComponent() method 
LayoutManager interface, 345 
LayoutManager2 interface, 345 
addListSelectionListener() method 
JList class, 476 
addSelectedInterval() method 
JList class, 479 
addSeparator() method 
JMenu class, 169, 175 
JPopupMenu class, 177, 178, 182 
JToolBar class, 208 
addTab() method 
JTabbedPane class, 398 
addUndoableListener() method 
UndoableEditSupport class, 794 
AdjustmentListener interface 
handling JScrollBar events, 423 
adjustmentListeners property 
JScrollBar component, 426 
alignment property 
TabStop class, 604 
alignmentX property 
JComponent class, 78 
alignmentY property 
JComponent class, 78 
allFrames property 
JDesktopPane component, 263 
allowsChildren property 
DefaultMutableTreeNode interface, 663 
AncestorListener event handler 
JComponent class, 81 
anchorSelectionIndex property 
DefaultListSelectionModel class, 475, 683 
JList class, 464 
anchorSelectionPath property 
JTree class, 628, 630 
approveButtonMnemonic property 
JFileChooser class, 327 
approveButtonText property 
JFileChooser class, 327 
approveButtonToolTipText property 
JFileChooser class, 327 
armed property 
DefaultButtonModel interface, 100 
JMenultem class, 164 
ArrayList class 
converting data structure to ListModel, 453 


asynchronousLoadPriority property 
AbstractDocument class, 540 
AttributeContext interface, 595 
attributeCount property 
SimpleAttributeSet class, 598 
attributeNames property 
SimpleAttributeSet class, 598 
attributes property 
HTMLDocument.Iterator class, 609 
AttributeSet interface, 585 
changing and checking status with 
StyleConstants class, 603 
constants, 598, 599 
introduction, 597 
setting JTextPane text attributes, 580 
SimpleAttributeSet class 
implementation, 597 
specifying with Style interface, 606 
styles, 595 
autoCreateColumnsFromModel property 
JTable class, 681, 708 
autoResizeMode property 
JTable class, 681 
autoscrolls property 
JComponent class, 79 
auxiliaryLookAndFeels property 
UlManager class, 748 
AWT (Abstract Window Toolkit), 1 
AWT 1.1 event model 
handling JScrollBar events, 423 
AWT components 
AWT containers compared to Swing 
containers, 235 
distinction between equivalent Swing 
components, 3 
layout managers, 343 
mapping to Swing components, 3 
replacements, 3 
resizing, 388 
Swing menu components, 156 
to Swing Window mapping, 4 
AWTEvent class 
getIDO method, 257 
AWTEventMulticaster class 
managing listener lists, 29, 31, 32 
AWTRKeysStroke class 
KeyStroke class as subclass of, 42 


B 
background property 
Component class, 682 
DefaultTreeCellRenderer class, 635 
JComponent class, 78 
backgroundNonSelectionColor property 
DefaultTreeCellRenderer class, 635 
backgroundSelectionColor property 
DefaultTreeCellRenderer class, 635 
backgroundSet property 
JComponent class, 78 
BadLocationException class, 599 
BasicColorChooserUlI class, 309 
BasicComboBoxEditor class 
javax.swing.plaf.basic package, 499 
BasicDirectoryModel class 
ListModel implementation, 452 
BasicLookAndFeel class, 741 
initClassDefaults() method, 771 
look and feel classes extend from, 813 
BasicMenuUI class, 199 
BasicSplitPaneDivider subclass, 389 
BasicSplitPaneUlI subclass 
createDefaultDivider() method, 389 
BasicTextAreaUI interface, 60 
beginUpdate() method 
UndoableEditSupport class, 794 
BevelBorder class, 220 
methods, 221 
bidiRootElement property 
AbstractDocument class, 540 
black property 
MetalLookAndrFeel class, 772 
blinkRate property 
Caret interface, 548 
blockIncrement property 
JScrollBar component, 421, 426 
Border interface 
javax.swing.border package, 212 
methods, 212 
border property 
JComponent class, 78, 441 
JViewport class, 412 
TitledBorder class, 229 
BorderFactory class 
javax.swing package, 215 
BorderLayout class 
introduction, 347, 348, 349 
using LayoutManager2 interface, 345 
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BorderLayout manager, 204 
default layout manager for JApplet 
class, 252 
borderOpaque property 
CompoundBorder class, 227 
LineBorder class, 220 
TitledBorder class, 229 
borderPainted property 
AbstractButton class, 98 
JMenuBar class, 159 
JPopupMenu class, 179 
JProgressBar component, 440, 441 
JToolBar class, 203 
borderPaintedFlat property 
JCheckBox class, 127, 128 
borders, 211 
basics, 211 
AbstractBorder class, 216 
Border interface, 212 
BorderFactory class, 215 
creating, 232, 234 
predefined borders, 218 
BevelBorder class, 220 
CompoundBorder class, 226 
EmptyBorder class, 218 
EtchedBorder class, 223 
LineBorder class, 219 
MatteBorder class, 224 
SoftBevelBorder class, 222 
TitledBorder class, 227 
borderSelectionColor property 
DefaultTreeCellRenderer class, 635 
bottomComponent property 
JSplitPane class, 385, 386 
bounded range components 
available components, 419 
BoundedRangeModel interface, 419 
DefaultBoundedRangeModel class, 420 
JProgressBar class, 439-447 
JScrollBar class, 421-428 
JSlider class, 428-438 
BoundedRangeModel interface 
definition, 420 
getModel() method, 426 
JTextField class, 447, 449 
properties, 419 
bounds property 
JComponent class, 77 
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Box class CannotUndoException class, 784, 790 
BoxLayout class as default layout manager CardLayout class 
of container, 357 compared to JTabbedPane class, 394 
creating, 378 introduction, 357 
creating areas that grow, 380-381 using LayoutManager2 interface, 345 
creating rigid areas, 382-383 caret category of properties 
introduction, 377 JTextComponent class, 524 
properties, 379 Caret interface, 522 
Box.Filler class. See Filler class introduction, 547-550 
BoxLayout class properties, 548 
as default layout manager of Box class, 377 caret property 
creating, 358 JTextComponent class, 523 
filling box with JLabel, JTextField, and caretColor property 
JButton, 378 JTextComponent class, 523 
growing components, 380 CaretEvent class 
introduction, 357, 358 introduction, 550-552 
laying out components, 359 CaretListener interface 
with different alignments, 362 associating with JTextComponent, 550 
with same alignments, 359-361 introduction, 550-552 
laying out larger components, 363, 364 caretListeners property 
layout manager for JMenuBar class, 381 JTextComponent class, 523 
breadthFirstEnumeration() method caretPosition property 
DefaultMutableTreeNode class, 665 JTextComponent class, 523 
ButtonGroup class caretUpdate() method 
grouping JRadioButton components in, CaretListener interface, 551 
136-139 cell editor, 718 
grouping objects into, 98 creating complex version, 722-724 
introduction, 116-118 creating simple version, 718-722 
logical grouping of AbstractButton CellEditor interface, 644 
components, 115 and CellEditorListener interface 
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implements ComboBoxModel 
interface, 451 
introduction, 460-463 
DefaultDesktopManager class, 252 
implementation of DesktopManager 
interface, 266 
DefaultEditor class 
properties, 518 
DefaultEditorKit class 
class constants, 591 
copyAction class constant, 592 
cutAction class constant, 592 
cutAction() method, 535 
pasteAction class constant, 592 
readOnlyAction class constant, 592 
writableAction class constant, 592 
DefaultFocusManager class, 47 
DefaultFocusTraversalPolicy 
FocusTraversalPolicy class, 53 
DefaultFormatterFactory class 
javax.swing.text package, 620, 621 
DefaultHighlighter class, 547 
DefaultHighlighter.HighlightPainter class, 547 
DefaultKeyboardFocusManager class, 37, 55 
defaultLeaflcon property 
DefaultTreeCellRenderer class, 635 
DefaultListCellRenderer class, 468 
and ListCellRenderer interface, 468, 470 
DefaultListModel class 
data model implementation of JList, 451 
introduction, 453 
methods, 459 
DefaultListSelectionModel class 
properties, 475, 683 
defaultLookAndFeelDecorated property 
JDialog class, 250 
JFrame class, 244 
DefaultMenuLayout class 
javax.swing.plaf.basic package, 381 


INDEX 


DefaultMetalTheme class 
introduction, 774 
DefaultMutableTreeNode class, 624 
building hierarchies, 661, 662 
creating, 661 
DynamicUtilTreeNode as subclass of, 666 
properties, 663 
traversing trees, 664 
userObject property, 640, 666 
working with tree nodes, 661-664 
DefaultMutableTreeNode interface 
querying node relationships, 664 
defaultOpenIcon property 
DefaultTreeCellRenderer class, 635 
defaultRootElement property 
AbstractDocument class, 540 
DefaultStyledDocument class, 596 
defaults property 
LookAndFeel class, 742 
UlManager class, 748 
DefaultSingleSelectionModel class, 395 
default implementation of 
SingleSelectionModel interface, 162 
DefaultStyledDocument class, 521, 574, 595 
creating, 596 
implementation of StyledDocument 
interface, 596 
properties, 596 
DefaultTableCellRenderer class, 686, 687 
DefaultTableColumnModel class 
implementation of TableColumnModel 
interface, 676 
properties, 708 
used when TableColumnModel interface 
is not specified, 678 
DefaultTableModel class 
creating, 696, 697 
creating sparse table model, 698, 699 
encapsulates TableModel interface, 676 
filling, 697 
introduction, 696 
listening to JTable events with 
TableModelListener, 699 
properties, 697 
DefaultTreeCellEditor class, 644 
combining with DefaultCellEditor class, 648 
implementation of TreeCellEditor class, 623 
introduction, 647 
using for a JTextField editor with JTree, 645 


857 


858 


INDEX 


DefaultTreeCellRenderer class 
configuring, 651 
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getKeyStroke() method 
KeyStroke class, 43 
getKeyStrokeForEvent() method 
KeyStroke class, 43 
getKeyText() method 
KeyEvent class, 29 
getLastComponent() method 
FocusTraversalPolicy class, 52 
getListCellRendererComponent() method 
ListCellRenderer interface, 469 
getListDataListeners() method 
AbstractListModel class, 452 
getListeners() method 
Component class, 29 
DefaultBoundedRangeModel class, 421 
getMaxCharactersPerLineCount(O) method 
JOptionPane class, 281 
getModel() method 
BoundedRangeModel interface, 426, 431 
getName() method 
Component class, 397 
getNextMatch() method 
JList class, 481 
getNextNode() method 
DefaultMutableTreeNode class, 664 
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getNextVisualPositionFrom( method 
NavigationFilter class, 552 
getObjectO) method 
UlManager class, 747 
getPaintTicks() method 
JSlider component, 435 
getPath(O method 
TreePath class, 673 
getPopupLocation() method 
JComponent class, 178 
getPreviewPanel() method 
ColorChooserComponentFactory class, 320 
getPreviousNode() method 
DefaultMutableTreeNode class, 664 
getProgress() method 
ProgressMonitor class, 293 
getPropertyO method 
AbstractDocument class, 540 
getPropertyName() method 
JInternalFrame class, 255 
getRoot() method 
TreeModel class, 666 
getSelectedElements() method 
JRadioButton class, 141 
getSelectedIndex() method 
JComboBox class, 495, 497 
getSelectedItem(O method 
JComboBox class, 495 
getSelection(O) method 
OptionPaneUtils class, 273, 274 
getSharedOwnerFrame() method 
SwingUtilities class, 277 
getSourceActions() method 
TransferHandler class, 734 
getStringO method 
UlManager class, 747 
getSubElements() method 
MenukElement interface, 195 
getSupportsWindowDecorations() method 
JRootPane class, 238 
getTableCellRendererComponent() method 
TableCellRenderer interface, 686, 687 
getTreeCellEditorComponent() method 
TreeCellEditor interface, 648, 656 
getUIO method 
UlManager class, 747 
getUIClassID() method 
JToolBar class, 763 
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getValue() method 
JOptionPane class, 272 
SpinnerDateModel class, 515 
glassPane property 
JDialog class, 250 
JFrame class, 243 
JInternalFrame class, 254 
JRootPane class, 237 
JWindow class, 248 
glue, creating, 380-381 
Graphics class 
translate() method, 214 
graphics property 
JComponent class, 78 
graphicsConfiguration property 
JComponent class, 78 
GrayFilter class, 97 
createDisabledImage() method, 97 
grid positioning 
GridBagConstraints class, 355, 356 
GridBagConstraints class 
and GridBagLayout class, 351 
component anchoring, 354 
component resizing, 354 
grid positioning, 355-356 
introduction, 353 
padding, 356 
weight, 357 
GridBagLayout class 
associating GridBagConstraints object to 
component, 345 
compared to BoxLayout class, 357 
components should have 
GridBagConstraints associated, 353 
introduction, 350-352 
rows and columns, 353 
using LayoutManager2 interface, 345 
gridColor property 
JTable class, 681-682 
GridLayout class 
compared to BoxLayout class, 357 
compared to GridBagLayout class, 350 
introduction, 349-350 
group property 
DefaultButtonModel interface, 100 
growing components, creating, 380-381 


H 
Hashtable class, 41 
createStandardLabels() method, 435 
creating JTree from, 625 
UlDefaults class as subclass, 749 
headerRenderer property 
TableColumn class, 713 
headerValue property 
TableColumn class, 713 
height property 
JComponent class, 77 
helpMenu property 
JMenuBar class, 159 
hide) method 
Popup class, 200 
HierarchyBoundsListener 
supported by JFrame class, 246 
HierarchyListener 
supported by JFrame class, 246 
highestLayer() method 
JLayeredPane class, 240 
Highlight class, 547 
highlightedTextColor property 
MetalLookAndrFeel class, 773 
highlighter category of properties 
JTextComponent class, 524 
Highlighter interface, 522 
introduction, 547-550 
highlighter property 
JTextComponent class, 523 
Highlighter.Highlight class, 547 
HighlightPainter class, 547 
horizontalAlignment property 
AbstractButton class, 98, 102 
JLabel class, 89 
JTextField class, 529, 530 
horizontalScrollBar property 
JScrollPane class, 407 
horizontalScrollBarPolicy property 
JScrollPane class, 407 
horizontalTextPosition property 
AbstractButton class, 98, 102 
JLabel class, 89 
horizontalVisibility property 
JTextField class, 529, 530 
HTML documents 
iterating through, 608-612 
loading as StyledDocument into 
JEditorPane, 607 


HTML.Tag class 

constants, 608, 609 

searching for tag types in document, 611 
HTMLDocument interface, 522 
HTMLDocument.Iterator class 

next() method, 609 

properties, 609 

using, 608, 610, 611 
HTML EditorKit class, 585 
HTMLEditorKit.Parser class 

javax.swing.text.html package, 607 
HTML EditorkKit.ParserCallback class, 607 
HTMLEditorKit.ParserDelegator class, 607 
HyperlinkEvent class, 574 
HyperlinkEvent.EventType class, 576 
HyperlinkListener interface, 574 

handling JEditorPane events example, 

577-578 

hyperlinkUpdate() method, 576 
hyperlinkListeners property 

JEditorPane class, 575 
hyperlinkUpdate(O) method 

HyperlinkListener interface, 576 
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I/O operations 
JTextComponent class, 526 
icon argument 
JOptionPane class, 270 
Icon interface, 92 
creating, 93, 94 
displaying images within components, 67 
javax.swing package, 734 
paintIcon() method, 93 
using, 94 
icon property 
AbstractButton class, 98 
ImagesSelection class, 734 
JInternalFrame class, 254, 255 
JLabel class, 89 
JOptionPane class, 281 
iconHeight property 
Imagelcon class, 96 
iconifiable property 
JInternalFrame class, 254 
iconImage property 
JFrame class, 243 
icons 
JMenultem and subclasses inherit 
support, 156 
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iconTextGap property 
JLabel class, 89 
iconWidth property 
Imagelcon class, 96 
ID property 
LookAndFeel class, 742 
identifier property 
TableColumn class, 713 
ignoreRepaint property 
JComponent class, 78 
IllegalArgumentException class 
and GridLayout class, 350 
can be caused by 
MutableTreeNode.insert(), 661 
changing border of JViewport class, 412 
creating JProgressBar components, 440 
creating JScrollbar components, 423 
creating JSlider components, 429 
creating JTabbedPane class, 396 
moving JSplitPane divider, 387 
setting delay property of Menu class, 172 
setting orientation of JSplitPane class, 386 
setting policies for JScrollPane class, 405 
image property 
Imagelcon class, 96 
Imagelcon class, 94 
creating, 95, 805-806 
predefined images, 67 
properties, 96 
using, 95 
imageLoadStatus property 
Imagelcon class, 96 
imageObserver property 
Imagelcon class, 96 
images, drag-and-drop support, 733 
ImageSelection class 
creating, 734 
icon property, 734 
importData() method 
TransferHandler class, 734-735 
inactiveControlTextColor property 
MetalLookAndrFeel class, 773 
inactiveSystemTextColor property 
MetalLookAndrFeel class, 773 
indeterminate property 
JProgressBar component, 440 
index0 property 
ListDataEvent class, 454 
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indexl property 
ListDataEvent class, 454 
indexOf() method 
DefaultListModel class, 460 
INFORMATION_MESSAGE pop-up 
JOptionPane class, 277 
inheritsPopupMenu property 
JComponent class, 79 
initClassDefaults() method 
BasicLookAndFeel class, 771 
initialDelay property 
Timer class, 36 
ToolTipManager class, 87 
initialSelectionValue property 
JOptionPane class, 281 
initialValue argument 
JOptionPane class, 271 
initialValue property 
JOptionPane class, 281 
inProgress property 
CompoundEdit class, 791 
inputAttributes property 
JTextPane class, 581 
inputContext property 
JComponent class, 79 
InputEvent class, 23 
InputMap class 
ActionMap class, 37 
getting for component based on focus 
activation condition, 43 
Keymap interface, 544 
inputMap property 
JComponent class, 41, 79 
InputMethodListener 
supported by JFrame class, 246 
inputMethodRequests property 
JComponent class, 79 
JTextComponent class, 523 
inputValue property 
JOptionPane class, 281, 284 
InputVerifier interface, 37 


component-level verification during focus 


traversal, 56 
listening to JTextField events, 558 
setVerifyinputWhenFocusTarget() 
method, 57 
inputVerifier property 
JComponent class, 78 


insert) method 
MutableTreeNode interface, 660, 662 
insertElementAt() method 
DefaultListModel class, 453 
insertNodelnto() method 
DefaultTreeModel class, 668 
insertSeparator() method 
JMenu class, 175 
insertString(O) method 
Document interface, 583 
DocumentFilter class, 542 
insertUpdate() method 
DocumentListener interface, 546 
insets property 
JComponent class, 78 
JViewport class, 412 
insideBorder property 
CompoundBorder class, 227 
installChooserPanel() method 


AbstractColorChooserPanel class, 312, 313 


installedLookAndFeels property 
UlManager class, 748 
intercellSpacing property 
JTable class, 681, 682 
InternalFrameAdapter class, 253 
InternalFrameListener methods, 256 
InternalFrameEvent class, 253 
constants for event subtypes, 257 
InternalFrameFocusTraversalPolicy 
FocusTraversalPolicy class, 53 
InternalFramelconifyListener class, 264 
InternalFramelListener interface, 253 
definition, 256 
methods, 256 
internalFrameListeners property 
JInternalFrame class, 254 
InternationalFormatter class 
java.swing.text package, 612 
INTERVAL_ADDED type constant 
ListDataEvent class, 455 
INTERVAL_REMOVED type constant 
ListDataEvent class, 455 
inverted property 
JSlider component, 431 
invokeAndWait() method 
EventQueue class, 21, 34 
SwingUtilities class, 23 


invokeLater() method 
EventQueue class, 21, 22, 34, 746 
SwingUtilities class, 23 
invoker property 
JPopupMenu class, 179 
invokesStopCellEditing property 
JTree class, 628 
IOException class 
thrown by read /write methods of 
JTextComponent class, 530 
isBorderOpaque() method 
AbstractBorder class, 217 
Border interface, 214 
isCellEditable() method 
CellEditor interface, 648, 655 
isDispatchThreadQ) method 
EventQueue class, 21 
isEventDispatchThread(O) method 
SwingUtilities class, 21 
isFilled property 
JSlider component, 438 
isInProgress() method 
UndoManager class, 792 
isLeftMouseButton(O) method 
SwingUtilities class, 24 
isMiddleMouseButton() method 
SwingUtilities class, 24 
isNodeAncestor() method 
DefaultMutableTreeNode interface, 664 
isNodeChild(O) method 
DefaultMutableTreeNode interface, 664 
isNodeDescendant() method 
DefaultMutableTreeNode interface, 664 
isNodeRelatedO) method 
DefaultMutableTreeNode interface, 664 
isNodeSiblingO method 
DefaultMutableTreeNode interface, 664 
isRightMouseButton(O) method 
SwingUtilities class, 24 
isSelectedIndex() method 
DefaultListSelectionModel class, 475 
isTraversable() method 
FileSystemView class, 334 
itemCount property 
JComboBox class, 492 
JMenu class, 171 
ItemListener interface 
handling JCheckBox selection events, 130 
handling JCheckBoxMenultem selection 
events, 187 
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handling JRadioButton selection 
events, 142 
handling JRadioButtonMenultem 
selection events, 192 
handling JToggleButton selection events, 
121-124 
listening to JComboBox events, 493-496 
itemListeners property 
AbstractButton class, 98 
JComboBox class, 492 
Iterator class 
using instead of Enumeration class, 666 
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Japanese-language buttons 
JOptionPane class, 291 
JApplet class 
BorderLayout class as default layout 
manager for, 347 
extending, 252 
introduction, 252 
JAR files, 1 
Java Access Bridge 
working with, 808-810 
Java archive, 1 
Java Ferret, introduction, 810 
java.awt package 
Color class, 730 
FocusTraversalPolicy class, 47 
KeyboardFocusManager, 47 
java.awt.datatransfer package 
drag-and-drop capabilities, 729 
Transferable interface, 733 
java.awt.event package 
KeyEvent class, 163 
java.beans package 
PropertyChangeListener, 420 
java.io package 
File class, 333, 730 
FileFilter interface, 331 
java.swing package 
TransferHandler class, 731 
java.swing.text package 
InternationalFormatter class, 612 
java.text package 
DecimalFormat class, 520 
Format class, 566 
MessageFormat class, 727 
NumberFormat class, 615 


867 


868 


INDEX 


java.util package 
Dictionary class, 641 
Hashtable class, 41 
Map interface, 41 
Timer class, 36 
Undo Framework, 783 
javax.accessibility package 
accessibility classes, 805 
javax.swing package, 2 
BorderFactory class, 215 
DefaultFocusManager class, 47 
filechooser class, 331 
FocusManager class, 47 
Icon class, 734 
javax.swing.border package 
AbstractBorder class, 216 
Border interface, 212 
javax.swing.colorchooser package 
support classes for JColorChooser 
class, 301 
javax.swing.event package, 32 
EventListenerList class, 29, 33 
event-related classes, 624 
support for Undo Framework, 783 
javax.swing.filechooser package 
support classes for JFileChooser, 322 
javax.swing.plaf package, 2 
classes that implement UTResource 
interface, 753-754 
javax.swing.plaf.basic package 
BasicComboBoxEditor class, 499 
DefaultMenuLayout class, 381 
javax.swing.plaf.metal package 
MetalLookAndrFeel class, 748, 772 
javax.swing.table package 
support classes for JTable class, 675 
javax.swing.text package 
DefaultFormatterFactory class, 620, 621 
javax.swing.text.html package 
HTML EditorKit.Parser class, 607 
javax.swing.tree package 
tree specific classes, 624 
javax.swing.undo package, 11 
Undo Framework, 783 
JButton class, 67, 104, 722 
ActionEvent event, 107 
addActionListener() method, 20 
changing look and feel at runtime 
through, 744-746 


configuring a default button, 105 

creating, 104 

customizing look and feel, 108 
UlResource-related properties, 109 

generating ActionEvent objects, 19 

getActionListeners() method, 29 

handling events, 106, 107 

placingicon onto, 271 

properties, 105 

using on JOptionPane, 285 


JCheckBox class 


appearance with DefaultCellEditor as 
TreeCellEditor, 646 

compared to JCheckBoxMenultem 
component, 185 

creating, 126-127 

creating CheckBoxNodeEditor class, 
653-658 

customizing look and feel, 133 

UlResource-related properties, 134 

editing table cells, 718 

handling selection events, 130-133 

introduction, 125 

properties, 127-130 


JCheckBoxMenultem component, 8 


compared to JRadioButtonMenultem 
component, 190 
creating, 184 
customizing look and feel, 187 
UlResource-related properties, 187, 189 
handling selection events, 186 
with ActionListener, 186 
with ItemListener, 187 
introduction, 184 
properties, 185 


JColorChooser class, 9, 722 


built-in drag-and-drop support, 730 

changing color chooser panels, 310-320 

changing preview panel, 308-309 

creating, 301 

creating and showing in pop-up window, 
303-307 

dragging-and-dropping colors across, 730 

introduction, 300-301 

listening for color selection changes, 303 

properties, 307 

providing OK/cancel event listeners, 305 

using, 302 


JComboBox class, 64, 314, 719 


changing look and feel at runtime 
through, 744-746 

creating components, 491 

customizing look and feel, 503-506 

data model provided by 
DefaultComboBoxModel class, 460 

demonstrating use of, 462-463 

editing elements, 497-503 

editing table cells, 718 

introduction, 490, 491 

properties, 491, 492 

rendering elements, 493 

selecting elements, 493-497 

sharing data model with JList, 506, 508 

uses implementation of ComboBoxModel 
interface, 460 
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component-set-oriented properties, 78 
event support properties, 79 
focus-oriented properties, 78 
focusTraversalPolicyProvider 
property, 50 
internationalization support 
properties, 79 
layout-oriented properties, 78 
Opaque property, 525 
other properties, 79 
painting properties, 70, 78 
painting support properties, 78 
position-oriented properties, 77 
state support properties, 79 
Swing menu elements are subclasses 
of, 156 
UlResource properties, 72 
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using with DefaultCellEditor as 
TreeCellEditor, 647 
JComboBoxMenultem class 
using with MenuElement interface, 195 
JComponent class 


JDesktopIcon class 
changing, 261 
inner class of JinternalFrame, 252 
JDesktopPane component, 8 
adding internal frames to, 262 


adding to JColorChooser, 308 
compared to AWT Component and 
Container classes, 67 
customizing display characteristics tooltip 
objects, 84 
descendent classes, 67 
handling events, 80 
listening to inherited events, 82, 84 
with AncestorListener, 81 
with PropertyChangeListener, 80 
with VetoableChangelListener, 81 
implements Accessible interface, 807 
introduction, 67 
methods 
currentManager() method, 70 
getActionMapO method, 593 
getClientProperty() method, 759 
getInputMapQ method, 43 
putClientPropertyO method, 759 
setComponentPopupMenul 
method, 178 
setMinimumsSize() method, 388 
setToolTipText(O) method, 84, 87 
painting JComponent objects, 69 
properties, 41, 74-77 
border property, 441 
client properties, 73 


and JInternalFrame class, 253 

as a specialized JLayeredPane, 252 
complete desktop example, 263-265 
creating, 262 

customizing look and feel, 263 
introduction, 262 

properties, 262 


JDialog class 


BorderLayout class as default layout 
manager for, 347 

creating, 248-249 

extending, 252 

handling events, 250-252 

introduction, 248 

placing JOptionPane class within, 271-272 

properties, 250 

setUndecorated() method, 237 


JEditorPane class, 5 


as subclass of JTextComponent class, 521 
built-in drag-and-drop support, 730 
creating, 575 
customizing look and feel, 579 
UlResource-related properties, 579 
handling events, 576-579 
HTMLDocument interface, 522 
JTextPane as subclass of, 521 
introduction, 574 
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loading HTML documents as 
StyledDocument, 607 

properties, 575-576 

JFileChooser class, 452 

adding ActionListener, 324-325 

creating, 323 

customizing look and feel, 336 

dragging-and-dropping File object, 730 

introduction, 322 

properties, 326 

showing in pop-up window, 326 

using, 323-324 

working with file filters, 328 
adding accessory panels, 331 
choosing directories instead of files, 331 
using FileSystemView class, 333 
using FileView class, 334-336 

JFormattedTextField class, 7 

and DefaultFormatterFactory class, 621 

and JSpinner class, 509 

built-in drag-and-drop support, 730 

creating, 566-567 

customizing look and feel, 569 
UlResource-related properties, 569-570 

date and time formats, 612-614 

example, 567-569 

finding actions, 591 

formats, 612 

input masks, 618-620 

introduction, 566 

properties, 567 

notify-field-accept action, 587 

number formats, 615-617 

setMask() method, 618 

setText() method, 615 

setValue() method, 615 

using formatted input options and 

validation available, 585 
working with editors based on, 518 


creating, 243 

defaultLookAndFeelDecorated 
property, 244 

extending, 246 

handling events, 245 

introduction, 242 

properties, 243 

setting window decoration style, 244 

setUndecorated() method, 237 


JInternalFrame class, 8 


and JDesktopPane, 266 
BorderLayout class as default layout 
manager for, 347 

changing JDesktoplIcon, 261 

creating, 253 

customizing look and feel, 257 
UlResource-related properties, 259-261 

handling events, 256-257 

introduction, 253 

palette with other frames, 261 

placing JOptionPane class within, 271 

properties, 254-255 

property constants, 255-256 

without AWT counterpart, 235 


JIT compilers, 1 
JLabel class, 67 


AccessibleJLabel class, 806 

creating, 89 

customizing look and feel, 92 

UlResource value settings, 92 

DefaultListCellRenderer class as subclass 
of, 468 

dragging text from, 732 

event handling, 91 

implementation of within 
TableCellRenderer interface, 676 

introduction, 88 

properties, 89 

setDisplayedMnemonic() method, 527 


JFormattedTextField. 
AbstractFormatterFactory class 
manages use of formatter objects, 617 
JFrame class 


setLabelFor() method, 528 
JLayeredPane class 

adding components in layers, 240-241 

as component of JRootPane class, 235 


adding components, 245 

BorderLayout class as default layout 
manager for, 347 

close operation constants, 244 

compared to JInternalFrame class, 253 


component layers and positions, 241 
creating, 240 

introduction, 239-240 

properties, 242 


JList class 


adding element level tooltips, 488-490 
creating components, 463-464 
creating dual list box, 481-488 
customizing look and feel, 480 
UlResource-related properties, 480-481 
data model implementation, 451 
displaying multiple columns, 479-480 
introduction, 463 
properties, 464-465 
rendering elements, 468-470 
creating complex ListCellRenderer, 
471-473 
scrolling components, 466-468 
scrolling support, 406 
selecting elements, 473-479 
sharing data model with JComboBox 
506, 508 


JMenu class 


adding menu items to, 169 
addSeparator() method, 175 
creating, 168-169 
customizing look and feel, 173 
UlResource-related properties, 173-175 
insertSeparator() method, 175 
introduction, 168 
listening to events 
with ChangelListener, 173 
with MenuListener, 173 
properties, 171 
setting menu components, 172 
using Action objects, 170, 171 


JMenuBar class 


adding Action objects, 589 

adding glue component to, 381 

adding to or removing menus from menu 

bars, 157-158 

and JApplet class, 252 

changing layout manager, 161 

contained in JLayeredPane class, 236 

creating, 157 

customizing look and feel, 159 
UlResource-related properties, 160 

introduction, 157 

properties, 158-159 

setHelpMenu( method, 381 


jMenuBar property 


JDialog class, 250 
JFrame class, 243 
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JInternalFrame class, 254 
JRootPane class, 237 


JMenultem class 


creating, 162-163 

customizing look and feel, 167 
UlResource-related properties, 167-168 

handling events, 164-167 

introduction, 162 

properties, 163 

setText() method, 589 


JOptionPane class, 9 


adding components to button area, 285 
adding components to message area, 284 
automatically creatingin pop-up window, 
274-275 
arguments for factory methods, 276 
confirm pop-ups, 278 
input pop-ups, 278-279 
message pop-ups, 277 
option pop-ups, 280 
createDialog() method, 292 
creating, 268-269 
creating JDialog class, 249 
creating pop-up dialogs hosted by 
JInternalFrame class, 254 
customizing look and feel, 287-291 
displaying, 271-274 
displaying multiline messages, 281-282 
initialValue argument, 271 
introduction, 267-268 
listening for property changes, 286 
message argument, 269-270 
message property, 283 
messageType argument, 270 
options argument, 271 
optionType argument, 270 
properties, 280-281 
showInternalMessageDialog(O 
method, 277 
showMessageDialog(O) method, 277 


JPanel class, 67 


AbstractColorChooserPanel as JPanel 
subclass, 312 

creating, 110 

customizing look and feel, 112 

UlResource-related properties, 112 

FlowLayout class as default layout 
manager for, 345 

implementing Accessible interface, 807 
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mixing lightweight and heavyweight 
components, 179 
placing JRadioButton objects within, 227 
setting previewPanel property to empty 
JPanel, 308 
using, 110-112 
JPasswordField class, 5 
built-in drag-and-drop support, 730 
creating, 563-564 
customizing look and feel, 565 
UlResource-related properties, 565 
finding actions, 591 
introduction, 563 
notify-field-accept action, 587 
properties, 564 
subclass of JTextField class, 521 
JPopupMenu class 
adding menu item to JMenu, 170 
adding menu items to, 177 
creating, 176 
customizing look and feel, 180 
UlResource-related properties, 181 
displaying, 178 
example, 182-184 
introduction, 176 
JMenu contained within, 168 
properties, 179 
Separator class, 182 
watching for pop-up menu visibility, 180 
JProgressBar component, 6 
creating, 439-440 
customizing look and feel, 446 
UlResource-related properties, 446 
handling events, 445-446 
introduction, 439 
labeling, 441 
painting borders, 441 
process of step through, 442-445 
properties, 440 
using an indeterminate progress bar, 442 
JRadioButton class 
compared to JRadioButtonMenultem 
component, 189 
creating, 135-136 
customizing look and feel, 147 
UlResource-related properties, 148 
grouping in a ButtonGroup, 136-139 
handling selection events, 139-145 
introduction, 134 


listing text actions, 586 
placing within JPanel, 227 
properties, 136 


JRadioButtonMenultem component, 8 


configuring properties, 191 

creating, 190 

customizing look and feel, 191 
UlResource-related properties, 191-192 

example, 192-194 

handling selection events, 190 

introduction, 184, 189 


JRootPane class 


and JDialog class, 248 

creating, 236 

creating JLayeredPane class, 240 
customizing look and feel, 238-239 
introduction, 235 

layering effect, 180 

properties, 236-238 

RootLayout inner class, 343 
windowDecorationStyle property, 244 


JScrollBar component 


BoundedRangeModel interface 
properties, 419 
compared to JSlider component, 6 
creating, 422 
customizing look and feel, 427 
UlResource-related properties, 427-428 
handling scrolling events, 423 
introduction, 421 
listening to scrolling events 
with AdjustmentListener, 423 
with ChangeListener, 424-425 
methods, 426 
properties, 14, 426 


JScrollPane class 


creating, 404-405 

creating columns that don't scroll, 692 

creating viewport view, 406 

customizing look and feel, 410 
UlResource-related properties, 410 

introduction, 403 

JScrollBar component used within, 421 

JTextComponent text components can be 

placed within, 523 

JViewport class used with, 371 

manually positioning JTable view, 679 

placing JList component within, 466 

placing JTableHeader objects within, 715 


placing JTextArea within, 570 
placing JTree within, 627 
placing tree within, 623 
policies, 405 
properties, 407 
resetting viewport position, 410 
Scrollable interface, 406 
use of ScrollPaneLayout class, 370 
using with JTable class, 678 
working with headers and corners, 409 
working with ScrollPaneLayout 
manager, 408 
JScrollPane.ScrollBar. See Scrollable 
interface 
JSeparator class, 8 
creating, 175 
customizing look and feel, 176 
UlResource-related properties, 176 
does not implement MenuElement 
interface, 195 
introduction, 175 
properties, 175 
setOrientation() method, 182, 208 
JSlider class, 6 
adding to JOptionPane, 284 
client properties, 438 
creating, 428-429 
customizing look and feel, 435-438 
displaying tick marks within, 432 
handling events, 430 
introduction, 428 
labeling positions, 434 
methods, 431 
properties, 431 
snapping thumb into position, 434 
UlResource-related properties, 437 
JSpinner class, 6 
creating, 510 
custom models, 517 
customizing look and feel, 512 
UlResource properties, 512-513 
editors, 518 
DateEditor class, 519 
DefaultEditor class, 518 
ListEditor class, 519 
NumberEditor class, 520 
introduction, 509 
listening for events with ChangeListener 
interface, 511-512 
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properties, 510-511 
SpinnerModel interface as data model, 513 


JSplitPane class, 10 


changing components, 386 

creating, 384 

customizing look and feel, 393 
UlResource-related properties, 393 

introduction, 383 

listening for property changes, 390-392 

moving divider, 387 

one-touch expandable divider, 388 

properties, 385 

resizing, 389 

resizing components, 388 

setting orientation, 386 


JTabbedPane class, 10 


adding and removing tabs, 397-398 

addTab() method, 398 

creating, 395-396 

customizing look and feel, 401 

UlResource-related properties, 402-403 

displaying multiple chooser panels in 
JColorChooser, 301 

introduction, 394 

listening for changing tab selection, 
399-401 

properties, 398-399 

used instead of CardLayout class, 357 


JTable class, 7, 677 


autoCreateColumnsFromModel 
property, 708 

auto-resize modes, 683-685 

createDefaultColumnsFromModel() 
method, 708 

creating, 677-678 

customizing look and feel, 689 

UlResource-related properties, 689-690 

display settings, 682 

editing table cells, 718 

example, 675 

handling events, 689 

listening to events with 
TableColumnModelListener, 709-712 

listing properties within with UlDefaults 
class, 749 

manually positioning view, 679 

preinstalled renderers, 695 

printO method, 724, 727 

properties, 680, 682 


873 


874 


INDEX 


removing column headers, 680 
rendering table cells, 686-689 
scrolling components, 678-679 
scrolling support, 406 
selection modes, 682, 683 
sorting elements, 700-707 
support classes, 675 


JTableHeader class, 676 


creating, 716 

customizing look and feel, 717 
introduction, 715 

properties, 716 

using tooltips in headers, 716, 717 


JTextArea class 


adding to window, 476 

as subclass of JTextComponent class, 521 
as view part of MVC, 59 

built-in drag-and-drop support, 730 
creating, 570 

customizing look and feel, 572 


UlResource-related properties, 573-574 


handling events, 572 

introduction, 570 

model and UI delegate, 60 
properties, 571, 572 

supporting undoable operations, 784 


JTextComponent class 


associating CaretListener interface 
with, 550 
associating NavigationFilter class with, 552 
drawingin the background of component, 
525-526 
getActions() method, 586 
getKeymap() method, 586 
introduction, 523 
modelToView() method, 549 
operations, 526 
operations with JTextField class, 530-537 
properties, 523 
read() method, 607 
registerKeyboardAction() method, 554 
scrolling support, 406 
setKeymap(Q method, 586 
subclasses, 521 
write() method, 607 


JTextComponent.KeyBinding class, 556 


JTextField class, 499 


as editor for JTree, 645 

as subclass of JTextComponent class, 521 

BoundedRangeModel interface, 447, 449 

built-in drag-and-drop support, 730 

creating, 527 

customizing look and feel, 562-563 

dragging text from JLabel class to 

JTextField class, 733 

editing JComboBox class elements, 498 

editing table cells, 718 

handling events, 556-562 

introduction, 526 

JPasswordField as subclass of, 521, 565 

JTextComponent operations, 530 
accessing the clipboard, 534-537 
loading and saving content, 530-534 

notify-field-accept action, 587 

properties, 529 

using JLabel mnemonics, 527-529 


JTextPane class, 5 


as subclass of JEditorPane component, 521 

built-in drag-and-drop support, 730 

creating, 580 

creating stylized text for display, 585 

customizing look and feel, 581 

DefaultStyledDocument class as data 
model, 596 

Hello, Java example, 600-601 
introduction, 580 

loading with content, 582-583 

populating StyledDocument for, 599 

properties, 580-581 


JToggleButton class, 6 


creating, 119-120 

customizing look and feel, 124 
UlResource elements, 125 

handling selection events, 121-124 

introduction, 119 

properties, 120 

ToggleButtonModel class as inner class 

of, 115 


JToggleButtonMenultem example, 195-199 
JToolBar class, 8, 784 


adding components to, 202 
creating, 202 

customizing look and feel, 205 
getUIClassID() method, 763 


handling events, 205 
introduction, 202 
properties, 203 
Separator class, 208 
usage example, 206-208 
JToolTip class, 7 
creating, 84 
creating customized objects, 84 
customizing look and feel, 86 
displaying positional tooltip text, 85 
properties, 85 
JTree class, 7 
convertValueToText() method, 642 
creating a proper ComboBox editor for, 648 
creating, 624-627 
creating custom renderer, 637-641 
customizing look and feel, 630-634 
DefaultTreeCellEditor class, 647 
DefaultTreeModel class, 667 
DynamicUtilTreeNode inner class, 624, 666 
editable property, 643 
EmptySelectionModel inner class, 624, 
669 
introducing trees, 623-624 
properties, 628-630 
scrolling support, 406 
scrolling trees, 627-628 
should use DefaultTreeCellEditor for 
JTextField editor, 645 
working with tree tooltips, 641-643 
JViewport class 
contained within JScrollPane, 403 
creating, 412 
customizing look and feel, 417 
introduction, 412 
keyboard movement control, 414-417 
properties, 412 
scroll modes, 414 
use of ViewportLayout class, 371 
usually used with JScrollPane class, 371 
JWindow class 
BorderLayout class as default layout 
manager for, 347 
creating, 247 
extending, 248 
fitting JPopupMenu menu items, 179 
handling events, 248 
introduction, 247 
properties, 248 
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KeyBinding class, 556 
KeyboardFocusManager class, 37, 48 
activeWindow property, 55 
focus management, 47 
focusedWindow property, 55 
focusOwner property, 55 
input focus behavior of Swing 
components, 55 
methods, 55 
KeyEvent class 
getKeyText() method, 29 
java.awt.event package, 163 
KeyListener class 
listening to JTextField events, 557 
sending keystrokes to ActionListener, 30 
supported by JFrame class, 246 
using, 586 
Keymap interface, 37 
addActionForKeyStroke() method, 45 
implementation as a wrapper to 
InputMap/ActionMap 
combination, 586 
introduction, 554-556 
maps KeyStroke to TextAction, 586 
keymap property 
JTextComponent class, 523, 554 
keys property 
AbstractAction class, 41 
KeySelectionManager interface, 195, 493 
keystroke manager for JComboBox 
class, 491 
listening to JComboBox keyboard 
events, 494 
keySelectionManager property 
JComboBox class, 492, 494 
KeyStroke class 
creating, 42 
getKeyStroke() method, 43 
getKeyStrokeForEvent() method, 43 
keystroke registration conditions, 42 
registering, 43, 44, 45 
registering to JTextComponent class, 554 
Swing-specific event handling, 37 
using, 586 
KeyTextComponent class 
registering ActionListener, 31 
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L 
label property 

AbstractButton class, 99 

JPopupMenu class, 179 
labelFor property 

JLabel class, 90, 91 
labelTable property 

JSlider component, 431 
largeModel property 

JTree class, 628, 630 
lastChild property 

DefaultMutableTreeNode interface, 663 
lastDividerLocation property 

JSplitPane class, 385, 389, 390, 392 


lastIndex property 
ListSelectionEvent class, 476 
lastindexOf(O method 
DefaultListModel class, 460 
lastLeaf property 


DefaultMutableTreeNode interface, 663 
lastPathComponent property 

TreePath class, 671 
lastRow property 

TableModelEvent class, 700 
lastSelectedPathComponent property 

JTree class, 628, 630 
lastVisiblelndex property 

JList class, 465, 468 
layer property 

JInternalFrame class, 254 
LayeredHighlighter class, 547 
LayeredHighlighter.LayerPainter class, 547 
layeredPane property 

JDialog class, 250 

JFrame class, 243 

JInternalFrame class, 254 

JRootPane class, 237 

JWindow class, 248 
LayerPainter class, 547 
layout management 

changing manager for JMenuBar class, 161 

changing manager for JTabbedPane 

class, 399 

Swing components, 10, 11 
layout managers 

See also AWT layout managers and Swing 

layout managers 
BorderLayout class, 347-349 
BoxLayout class, 357-364 


CardLayout class, 357 
FlowLayout class, 345-347 
GridBagConstraints class, 353-357 
GridBagLayout class, 350-353 
GridLayout class, 349-350 
introduction, 343 
LayoutManager interface, 344-345 
OverlayLayout class, 365-370 
responsibilities, 343-344 
ScrollPaneLayout class, 370 
SizeRequirements class, 370 
SpringLayout class, 371-375 
ViewportLayout class, 371 
layout property 
AbstractButton class, 98 
Box class, 379 
JComponent class, 78 
JDialog class, 250 
JFrame class, 243 
JInternalFrame class, 255 
JLayeredPane class, 240 
JScrollPane class, 407 
JToolBar class, 203 
JWindow class, 248 
LayoutFocusTraversalPolicy class 
focus management, 47 
FocusTraversalPolicy class, 53 
LayoutManager interface 
introduction, 344 
methods, 344 
LayoutManager2 interface 
methods, 345 
layoutOrientation property 
JList class, 465 
lazy, definition, 755 
LazyValue interface, 755 
creating, 755 
createValue() method, 755 
leadAnchorNotificationEnabled property 
DefaultListSelectionModel class, 475, 683 
leader property 
TabStop class, 604 
leadSelectionIndex property 
DefaultListSelectionModel class, 475, 683 
JList class, 465 
leadSelectionPath property 
DefaultTreeSelectionModel class, 670 
JTree class, 628, 630 


leadSelectionRow property 
DefaultTreeSelectionModel class, 670 
JTree class, 629-630 
leaf nodes 
creating editor for, 648-649 
leaf property 
DefaultMutableTreeNode interface, 663 
leafCount property 
DefaultMutableTreeNode interface, 663 
leaflcon property 
DefaultTreeCellRenderer class, 635 
left Component property 
JSplitPane class, 385-386 
length property 
AbstractDocument class, 540 
level property 
DefaultMutableTreeNode interface, 663 
lightweight property 
JComponent class, 79 
lightWeightPopupEnabled property 
JComboBox class, 492 
JPopupMenu class, 179 
ToolTipManager class, 87 
LineBorder class 
configuring properties, 220 
creating, 219 
lineColor property 
LineBorder class, 220 
lineCount property 
JTextArea class, 571 
lineWrap property 
JTextArea class, 571 
list model controls, 451 
See also individual controls 
list property 
SpinnerListModel class, 516 
ListCellRenderer interface, 719 


and DefaultListCellRenderer class, 468, 470 


cell renderer for JComboBox class, 491 
creating complex version, 471-473 
drawing elements of JList class, 463 
getListCellRendererComponent( 
method, 469 

making lazy, 755 

listData property 
JList class, 465 

ListDataEvent class 
properties, 454 
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ListDataListener class, 451 
list managed by DefaultListModel class, 453 
list management provided by 
AbstractListModel, 452 
listening for ListModel events, 454-460 
listening to JComboBox events, 497 
managed by ListModel interface, 452 
using, 455 
ListEditor class 
introduction, 519 
ListModel interface 
converting ArrayList data structure, 453 
data model for JList class, 463 
defines data model for JComboBox 
class, 491 
extended by 
ComboBoxModel interface, 460 
introduction, 451 
management of ListDataListener, 452 
partially implemented by 
AbstractListModel, 452 
ListSelectionEvent class 
properties, 476 
ListSelectionListener interface 
listening to JList events, 476-478 
registering with ListSelectionModel 
class, 683 
listSelectionListeners property 
DefaultListSelectionModel class, 475, 683 
JList class, 465 
ListSelectionModel interface, 676 
allowing users to select columns and rows 
from table, 708 
attaching ListSelectionListener, 476 
constants for different selection 
modes, 683 
controls selection process for JList, 473 
creating columns that do not scroll, 692 
default implementation is 
DefaultListSelectionModel class, 475 
handling JTable events, 689 
model for selecting elements of JList 
class, 463 
modes, 474 
multiple-selection mode, 678 
registering ListSelectionListener, 683 
settings control selection within table, 676 
load(O) method 
SynthLookAndFeel class, 780 
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locale property 
AccessibleContext class, 807 
JComponent class, 79 
localization 
NumberFormat class, 615 
locationOnScreen property 
JComponent class, 77 
locationTolndex() method 
JList class, 478 
logicalStyle property 
JTextPane class, 581 
look and feel architecture, 741 
creating new look and feel, 767-772 
LookAndFeel class, 741-766 
metal themes, 772 
SynthLookAndFeel class, 777-781 
using auxiliary look and feel, 776 
look and feel image files, 768-770 
LookAndFeel class 
as root class for specific look and feel, 741 
changing current look and feel, 743-747 
customizing current look and feel, 747 
creating new UI delegate, 763-766 
UlDefaults class, 749-752 
UlDefaults.ActiveValue, 
UlDefaults.LazyValue, and 
UlDefaults.ProxyLazyValue classes, 
755-759 
UlManager class, 747-749 
UlManager.LookAndFeelInfo class, 749 
UlResource interface, 753-755 
using client properties, 759-763 
introduction, 741-742 
listing installed classes, 742 
makelcon() method, 755 
lookAndFeel property 
UlManager class, 748 
lookAndFeelDefaults property 
UlManager class, 748 
lowestLayer() method 
JLayeredPane class, 240 
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MacLookAndFeel implementation 
LookAndFeel.supportedLookAndFeel, 742 
magicCaretPosition property 
Caret interface, 548 
majorTickSpacing property 
JSlider component, 431 


makelcon() method 
LookAndFeel class, 755 
Map interface, 41 
margin property 
AbstractButton class, 98 
JMenuBar class, 159 
JPopupMenu class, 179 
JTextComponent class, 523, 524 
JToolBar class, 203 
mark property 
Caret interface, 548 
MaskFormatter class, 566 
overwriteMode property, 620 
placeholderCharacter property, 620 
validCharacters property, 620 
MatteBorder class, 224 
color implementation, 225 
constructors and methods, 225 
Icon implementation, 225 
maxCharactersPerLineCount property 
JOptionPane class, 281, 282, 292 
maximizable property 
JInternalFrame class, 255 
maximum property 
BoundedRangeModel interface, 419 
JInternalFrame class, 255 
JProgressBar component, 440 
JScrollBar component, 426 
JSlider component, 431 
ProgressMonitor class, 296 
SpinnerNumberModel class, 517 
maximumDividerLocation property 
JSplitPane class, 385 
maximumRowCount property 
JComboBox class, 492 
maximumsSize property 
JComponent class, 78 
JScrollBar component, 426 
maximumsSizeSet property 
JComponent class, 78 
maxSelectionIndex property 
DefaultListSelectionModel class, 475, 683 
maxSelectionRow property 
DefaultTreeSelectionModel class, 670 
JTree class, 629, 630 
maxWidth property 
TableColumn class, 713 
menu components 
example, 152 
hierarchy, 156 


menuBackground property 

MetalLookAndrFeel class, 773 
menuComponentCount property 

JMenu class, 171 
menuComponents property 

JMenu class, 171 
menuCount property 

JMenuBar class, 159 
menuDisabledForeground property 

MetalLookAndrFeel class, 773 
MenuDragMouseEvent class 

definition, 167 
MenuDragMouseListener interface 

listening to JMenultem events, 167 
menuDragMouseListeners property 

JMenultem class, 164 
MenutElement interface, 157 

creating custom components, 195 
menuForeground property 

MetalLookAndrFeel class, 773 
MenuKeyListener interface 

listening to JMenultem events, 166 
menuKeyListeners property 

JMenultem class, 164 

JPopupMenu class, 179 
MenuListener interface 

listening to JMenu events, 173 
menulListeners property 

JMenu class, 172 
menus, adding to or removing from menu 

bars, 157, 158 

menusSelectedBackground property 
MetalLookAndrFeel class, 773 
menusSelectedForeground property 
MetalLookAndrFeel class, 773 
menuSelectionChanged() method 
MenukElement interface, 195 
MenusSelectionManager class, 167, 195 
menuTextFont property 
MetalLookAndrFeel class, 773 
message property 

JOptionPane class, 269, 270, 281, 283 
MessageFormat class 

java.text package, 727 
messageType property 

JOptionPane class, 270, 281 
Metal themes, creating, 774 
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MetalLookAndrFeel class 
addCustomEntriesToTable() method, 774 
currentTheme property, 774 
javax.swing.plaf.metal package, 748, 772 
properties, 772 

MetalLookAndFeel implementation 
LookAndFeel.supportedLookAndrFeel, 742 

Metalworks system demo 
examples for customizing themes, 775 

millisToDecideToPopup property 
ProgressMonitor class, 292, 296 

millisToPopup property 
ProgressMonitor class, 292, 296 

minimum property 
BoundedRangeModel interface, 419 
JProgressBar component, 440 
JScrollBar component, 426 
JSlider component, 431 
ProgressMonitor class, 296 
SpinnerNumberModel class, 517 

minimumDividerLocation property 
JSplitPane class, 385 

minimum)Size property 
JComponent class, 78 
JScrollBar component, 426 

minimumSizeSet property 
JComponent class, 78 

minorTickSpacing property 
JSlider component, 431 

minSelectionIndex property 
DefaultListSelectionModel class, 475, 683 
JList class, 465 

minSelectionRow property 
DefaultTreeSelectionModel class, 670 
JTree class, 629, 630 

minWidth property 
TableColumn class, 713 

mnemonic property 
AbstractButton class, 98 
DefaultButtonModel interface, 100 

mnemonics, 46 

model property 
AbstractButton class, 99 
DateEditor class, 519 
JComboBox class, 492 
JList class, 465 
JMenu class, 172 
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JProgressBar component, 440 

JScrollBar component, 426 

JSlider component, 431 

JSpinner class, 510 

JTabbedPane class, 399 

JTable class, 681 

JTree class, 629 

ListEditor class, 520 

NumberEditor class, 520 
modellndex property 

TableColumn class, 713 
modelToView() method 

JTextComponent class, 549 
ModifyModelSample program 

using DefaultListModel class modifying 

methods, 455-459 

mostRecentFocusOwner property 

JInternalFrame class, 255 
MotifButtonUI class 

getBorderInsets() method, 217 
MotifLookAndFeel implementation 

LookAndFeel.supportedLookAndFeel, 742 
mouseClicked(O) method 

MouselInputListener interface, 23 
mouseDragged() method 

MouseMotionlListener interface, 23 
mouseEntered() method 

MouselInputListener interface, 23 
MouseEnterFocusMover class 

programmatically moving focus, 49 
mouseExited() method 

MouselInputListener interface, 23 
MouselInputListener interface 

methods, 23 
MouseListener interface 

creating to handle input focus, 48 

requestFocusInWindow() method, 48 

supported by JFrame class, 246 
MouseMotionListener interface 

methods, 23 

supported by JFrame class, 246 
mouseMoved() method 

MouseMotionlListener interface, 23 
mousePosition property 

JComponent class, 79 
mousePressed() method 

MouselInputListener interface, 23 
mouseReleased() method 

MouselInputListener interface, 23 


moveDot() method 
Caret interface, 549 
NavigationFilter class, 552 
moveToBack() method 
JLayeredPane class, 241 
moveToFront() method 
JLayeredPane class, 241 
multiClickThreshhold property 
AbstractButton class, 99 
multiline messages 
displaying in JOptionPane, 281, 282 
MULTIPLE_INTERVAL_SELECTION mode 
ListSelectionModel interface, 474 
multiSelectionEnabled property 
JFileChooser class, 327 
multithreaded Swing event handling, 21, 23 
managing listener lists, 29 
AWTEventMulticaster class, 29-32 
EventListenerList, 32-34 
selectable button example, 22 
Timer class, 34-36 
using PropertyChangeListeners as 
Observers, 26-28 
using SwingUtilities class for mouse 
button identification, 23-26 
MutableAttributeSet interface, 585, 595 
adding name to with Style interface, 606 
introduction, 597 
modifying with StyleConstants class, 
602-603 
setting JTextPane text attributes, 580 
MutableComboBoxModel interface, 64, 451 
implementing DefaultComboBoxModel 
class, 461 
introduction, 460 
MutableTreeNode interface, 659 
insert) method, 662 
nodes of JTree are implementations of, 624 
working with tree nodes, 660 
MVC architecture, 11, 59 
BoundedRangeModel interface, 419 
flow described 
communication, 59 
UI delegates for Swing components, 60 
handling JScrollBar events, 423 
predefined data models, 63-64 
sharing data models, 61-63 


N 
name property 
JComponent class, 79 
LookAndFeel class, 742 
MetalLookAndrFeel class, 773 
UlManager.LookAndFeelInfo class, 749 
NamedsStyle class, 595, 606 
nativeLookAndFeel property 
LookAndFeel class, 742 
NavigationFilter class, 522 
introduction, 552 
restricting caret movement example 
552, 554 
navigationFilter property 
JTextComponent class, 523 
next() method 
ElementIterator class, 611 
HTMLDocument.Iterator class, 609 
nextLeaf property 
DefaultMutableTreeNode interface, 663 
nextNode property 
DefaultMutableTreeNode interface, 663 
nextSibling property 
DefaultMutableTreeNode interface, 663 
nextValue property 
JSpinner class, 510 
SpinnerDateModel class, 515 
SpinnerListModel class, 516 
SpinnerNumberModel class, 517 
nodeChanged() method 
DefaultTreeModel class, 668 
nodesChanged(O) method 
DefaultTreeModel class, 668 
nodeStructureChanged() method 
DefaultTreeModel class, 668 
nodesWerelnserted() method 
DefaultTreeModel class, 668 
nodesWereRemoved() method 
DefaultTreeModel class, 668 
non-AWT upgraded components, 5 
normalBounds property 
JInternalFrame class, 255 
note property 
ProgressMonitor class, 296 
notify-field-accept action 
extra action for JTextField, 
JFormattedTextField, and 
JPasswordEield, 587 
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Number object 
providing to JFormattedTextField 
constructor, 612 
number property 
SpinnerNumberModel class, 517 
NumberEditor class 
introduction, 520 
properties, 520 
NumberFormat class, 612 
java.text package, 615 
NumberFormatter class, 566 


0 
Observer design pattern 
delegation-based event handling, 17, 18 
event listeners as observers, 19 
OceanTheme class 
introduction, 774 
oneTouchExpandable property 
JSplitPane class, 386, 388 
opaque property 
JComponent class, 70, 78 
JDesktopPane component, 263 
JTextComponent class, 525 
openlIcon property 
DefaultTreeCellRenderer class, 635 
optimizedDrawingEnabled property 
JComponent class, 70, 78 
JLayeredPane class, 242 
JRootPane class, 237 
JViewport class, 412 
OptionPaneUtils class 
creating narrow JOptionPane, 281, 282 
getSelection() method, 273, 274 
options property 
JOptionPane class, 271, 281 
optionType property 
JOptionPane class, 270, 281 
orientation property 
JProgressBar component, 440 
JScrollBar component, 426 
JSeparator class, 175 
JSlider component, 431 
JSplitPane class, 386 
JToolBar class, 203 
outsideBorder property 
CompoundBorder class, 227 
OvalPanel class, 391 
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OverlayLayout class 
introduction, 365-370 

overwriteMode property 
MaskFormatter class, 620 


1») 
padding 
GridBagConstraints class, 356 
page property 
JEditorPane class, 575 
paint() method 
JComponent class, 69 
paintBorder() method 
AbstractBorder class, 217, 232 
Border interface, 212 
JComponent class, 69, 70 
paintChildren() method 
JComponent class, 69, 70 
paintComponent() method 
JComponent class, 69, 70 
JPanel class, 111 
paintIconO) method 
Icon interface, 93 
paintImmediatelyO method 
JComponent class, 70, 78 
paintingTile property 
JComponent class, 78 
paintLabels property 
JSlider component, 431 
paintTicks property 
JSlider component, 431 
paintTrack property 
JSlider component, 431 
Panel class 
displaying the menu choices, 179 
paragraphAttributes property 
JTextPane class, 581 
ParagraphConstants class 
keys for attributes, 598 
TabSet attribute, 603 
parent property 
DefaultMutableTreeNode interface, 663 
JComponent class, 77 
parentPath property 
TreePath class, 671 
password property 
JPasswordField class, 564 
paste() method 
JTextComponent class, 534 


pasteAction class constant 
DefaultEditorKit class, 592 
path property 
DefaultMutableTreeNode interface, 663 
TreePath class, 671 
pathByAddingChild() method 
TreePath class, 671 
pathCount property 
TreePath class, 671 
percentComplete property 
JProgressBar component, 441 
placeholderCharacter property 
MaskFormatter class, 620 
plaf, 2 
PlainDocument class, 60, 521 
implementation of Document 
interface, 526 
as data model for JTextArea, 570 
introduction, 541, 542 
PlainView view 
BasicTextAreaUl interface, 60 
Popup class 
creating, 200 
pop-up menu usage example, 182-184 
pop-up usage example, 200-202 
pop-up window 
showing JFileChooser in, 326 
PopupFactory class 
creating Popup objects, 200 
popupMenu property 
JMenu class, 172 
PopupMenuEvent event 
PopupMenuListener class, 180 
PopupMenuListener class 
watching for pop-up menu visibility, 180 
popupMenuListeners property 
JComboBox class, 492 
JPopupMenu class, 179 
popupMenuVisible property 
JMenu class, 172 
pop-ups, 267 
JOptionPane class 
automatically creating in pop-up 
window, 274-280 
creating, 268-271 
customizing look and feel, 287-291 
displaying, 271-274 
introduction, 267-268 
properties, 280-287 


ProgressMonitor class 
creating, 292 
customizing look and feel, 297 
introduction, 291-292 
properties, 296-297 
using, 293-296 
ProgressMonitorInputStream class 
creating, 297 
introduction, 297 
properties, 299 
using, 298-299 
popupSize property 
JPopupMenu class, 179 
popupVisible property 
JComboBox class, 492 
position constants 
JOptionPane class, 274 
position property 
TabStop class, 604 
positioning operations 
JTextComponent class, 526 
postEdit() method 
UndoableEditSupport class, 794 
preferredScrollableViewportSize property 
JList class, 465, 466 
JTable class, 681 
JTextArea class, 571 
JTextComponent class, 523 
JTree class, 629 
preferredSize property 
DefaultTreeCellRenderer class, 635 
JComponent class, 78 
JEditorPane class, 575 
JTextArea class, 571 
JTextField class, 529 
preferredSizeSet property 
JComponent class, 78 
preferredWidth property 
TableColumn class, 713 
preOrderEnumeration() method 
DefaultMutableTreeNode class, 665 
pressed property 
DefaultButtonModel interface, 100 
pressedIcon property 
AbstractButton class, 99 
previewPanel property 
JColorChooser class, 307, 308 
previous() method 
ElementlIterator class, 611 
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DefaultMutableTreeNode interface, 663 
previousNode property 


DefaultMutableTreeNode interface, 663 
previousSibling property 

DefaultMutableTreeNode interface, 663 
previousValue property 

JSpinner class, 510 

SpinnerDateModel class, 515 

SpinnerListModel class, 516 

SpinnerNumberModel class, 517 
primaryl property 
MetalLookAndrFeel class, 773 
primary2 property 
MetalLookAndrFeel class, 773 
primary3 property 
MetalLookAndrFeel class, 773 
primaryControl property 
MetalLookAndrFeel class, 773 
primaryControlDarkShadow property 
MetalLookAndrFeel class, 773 
primaryControlHighlight property 
MetalLookAndrFeel class, 773 
primaryControlInfo property 
MetalLookAndrFeel class, 773 
primaryControlShadow property 
MetalLookAndrFeel class, 773 
printQ method 

JTable class, 724, 727 
PrinterException class, 727 
printing tables, 724 
processKeyEvent() method 

MenukElement interface, 195 
processMouseEvent() method 

MenuElement interface, 195 
progress property 

ProgressMonitor class, 296 
ProgressMonitor class 

creating, 292 

introduction, 291-292 

properties, 296-297 

using, 293-296 
progressMonitor property 

ProgressMonitorInputStream class, 300 
ProgressMonitorHandler inner class, 294 
ProgressMonitorInputStream class 

creating, 297 

introduction, 297 

properties, 299 

using, 298-299 
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PropertiesList example 
demonstrating tooltips, 488, 490 
PropertyChangeListener, 420 
AbstractButton class, 102 
as accessory component for JFileChooser 
class, 331, 333 
JOptionPane, 287 
listening for JSplitPane property 
changes, 390 
supported by JFrame class, 246 
PropertyChangeListener interface 
event handler for JComponent class, 80 
using as Observers, 26, 27, 28 
propertyChangeListeners property 
AbstractAction class, 41 
TableColumn class, 713 
UlManager class, 748 
PropertyChangeSupport class, 26 
prototypeCellValue property 
JList class, 465, 466 
prototypeDisplayValue property 
JComboBox class, 492 
ProxyLazyValue class, 755 
associating with Tree.openIcon setting, 
756, 757 
deferring object creation, 755, 756 
put) method 
UlManager class, 747, 758 
putClientPropertyO) method 
JComponent class, 759 
putConstraint() method 
SpringLayout class, 372, 373 
putDefaults(Q method 
UlDefaults class, 749 
putProperty(O) method 
AbstractDocument class, 540 


Q 
QUESTION_MESSAGE pop-up 
JOptionPane class, 278 


R 
RadioButtonUtils class 
complete definition, 145 
createRadioButtonGrouping() method, 
137, 140 
listing text actions, 587 
read() method 
JTextComponent class, 530 


readOnlyAction class constant 
DefaultEditorKit class, 592 
redo() method 
CompoundEdit class, 792 
UndoableEdit interface, 790 
UndoManager class, 784 
registeredKeyStrokes property 
JComponent class, 79 
registerKeyboardAction() method 
JTextComponent class, 554 
reload() method 
DefaultTreeModel class, 668 
remove() method 
DocumentFilter class, 542 
JMenuBar class, 158 
JPopupMenu class, 178 
removeCellEditorListener() method 
CellEditor interface, 654 
removeChooserPanel() method 
JColorChooser class, 320 
removeElement() method 
DefaultListModel class, 454 
removelListenerListener() method 
JList class, 476 
removeNodeFromParent() method 
DefaultTreeModel class, 668 
removeSelectedInterval) method 
JList class, 479 
removeUpdate() method 
DocumentListener interface, 546 
renderer property 
JComboBox class, 492 
renderers, preinstalled 
JTable class, 695 
reorderingAllowed property 
JTableHeader class, 716 
repaint() method 
JComponent class, 69 
RepaintManager class 
customizing painting behavior, 69 
introduction, 70, 71 
properties, 71 
repeats property 
Timer class, 36 
replace() method 
DocumentFilter class, 542 
requestFocusEnabled property 
JComponent class, 78 


requestFocusInWindow() method 
MouseListener interface, 48 
resetToPreferredSizes() method 
JSplitPane class, 387 
reshowDelay property 
ToolTipManager class, 87 
resizable property 
JInternalFrame class, 255 
TableColumn class, 713 
resizeWeight property 
JSplitPane class, 386, 389 
resizingAllowed property 
JTableHeader class, 716 
resizingColumn property 
JTableHeader class, 716 
resolveParent property 
SimpleAttributeSet class, 598 
restart() method 
Timer class, 35 
restoreState method 
StateEditable interface, 800 
restoreState() method 
StateEditable interface, 801 
restricting focus cycle example, 51 
revalidate() method 
JComponent class, 70, 79 
reversing focus traversal, 53-55 
rightComponent property 
JSplitPane class, 386 
rigid component, creating, 382, 383 
rollover property 


DefaultButtonModel interface, 100 


JToolBar class, 203, 205 
rolloverEnabled property 
AbstractButton class, 99, 102 
rolloverlcon property 
AbstractButton class, 99, 102 
rolloverSelectedIcon property 
AbstractButton class, 99, 102 
root pane containers 
introduction, 235 
JApplet class, 252 
JDialog class, 248-252 
JFrame class, 242-247 
JLayeredPane class, 239-242 
JRootPane class, 235-239 
JWindow class, 247-248 


RootPaneContainer interface, 239 


working with a desktop, 252 
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JDesktopPane class, 262-266 
JInternalFrame class, 253-262 
root property 
DefaultMutableTreeNode interface, 663 
rootElements property 
AbstractDocument class, 540 
RootLayout class 
layout manager for JRootPane class, 
235-236 
RootLayout inner class, 343 
rootPane property 
JComponent class, 78 
JDialog class, 250 
JFrame class, 243 
JInternalFrame class, 255 
JWindow class, 248 
RootPaneContainer interface 
adding components to JFrame class, 245 
getting root pane, 236 
implemented by JApplet class, 252 
implemented by JDialog class, 248 
implemented by JInternalFrame class, 253 
introduction, 239 
rootVisible property 
JTree class, 629, 630 
roundedCorners property 
LineBorder class, 220 
rowCount property 
DefaultTableModel class, 697 
JTable class, 681 
JTree class, 629 
rowHeader property 
JScrollPane class, 407 
rowHeaderView property 
JScrollPane class, 407, 409 
rowHeight property 
JTable class, 681 
JTree class, 629 
RowMapper class 
implementation of TreePath class, 624 
RowMapper interface 
AbstractLayoutCache class 
implements, 670 
rowMapper property 
DefaultTreeSelectionModel class, 670 
rowMargin property 
JTable class, 681 
rows property 
JTextArea class, 571 
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rowSelectionAllowed property 
JTable class, 681, 682 
Runnable objects 
creating with EventQueue class, 21 
running property 
Timer class, 36 


S 
Scrollable interface, 404, 466 
definition, 406 
implemented by JTable class, 678 
implemented by JTextComponent 
class, 523 
implementation properties, 524 
implemented by JTree, 623, 627 
scrollableTracksViewportHeight property 
JEditorPane class, 575 
JList class, 465 
JTable class, 681 
JTextComponent class, 523 
JTree class, 629 
scrollableTracksViewportWidth property 
JEditorPane class, 575 
JList class, 465 
JTable class, 681 
JTextArea class, 571 
JTextComponent class, 523 
JTree class, 629 
Scrollbar component 
compared to JScrollBar and JSlider 
components, 6 
scrolling support 
Swing components, 406 
scrollMode property 
JViewport class, 412, 414 
scrollOffset property 
JTextField class, 529, 530 
ScrollPaneLayout class 
introduction, 370 
ScrollPaneLayout manager class 
locations, 408 
scrollPathToVisible() method 
JTree class, 627 
scrollRowToVisible() method 
JTree class, 627 
scrollsOnExpand property 
JTree class, 629, 630 
secondatyl property 
MetalLookAndrFeel class, 773 


secondary2 property 

MetalLookAndrFeel class, 773 
secondary3 property 

MetalLookAndrFeel class, 773 
selectAllQ) method 

ComboBoxEditor class, 499 
selected property 

AbstractButton class, 99 

DefaultButtonModel interface, 100 

JInternalFrame class, 255 

JMenu class, 172 

JMenuBar class, 159 

JPopupMenu class, 179 
selectedColor property 

ColorSelectionModel interface, 303 
selectedColumn property 

JTable class, 681-682 
selectedColumnCount property 

DefaultTableColumnModel class, 709 

JTable class, 681-682 
selectedColumns property 

DefaultTableColumnModel class, 709 

JTable class, 681-682 
selectedComponent property 

JTabbedPane class, 399 
selectedFile property 

JFileChooser class, 327 
selectedFiles property 

JFileChooser class, 327 
selectedFrame property 

JDesktopPane component, 263 
selectedIcon property 

AbstractButton class, 99 
selectedIndex property 

JComboBox class, 492 

JList class, 465 

JTabbedPane class, 399 
selectedIndices property 

JList class, 465 
selectedItem property 

DefaultComboBoxModel class, 461 

extended by ComboBoxModel 

interface, 460 

JComboBox class, 492 
selectedObjects property 

AbstractButton class, 99 

DefaultButtonModel interface, 100 

JCheckBoxMenultem component, 185 

JComboBox class, 492 


selectedRow property 
JTable class, 681-682 
selectedRowCount property 
JTable class, 681-682 
selectedRows property 
JTable class, 681-682 
selectedText property 
JTextComponent class, 524 
selectedTextColor property 
JTextComponent class, 524 
selectedValue property 
JList class, 465 
selectedValues property 
JList class, 465 
selection operations 
JTextComponent class, 526 
selectionBackground property 
JList class, 465 
JTable class, 681, 682 
TextField class, 547 
selectionColor property 
JTextComponent class, 524 
selectionCount property 
DefaultTreeSelectionModel class, 670 
JTree class, 629 
selectionEmpty property 
DefaultListSelectionModel class, 475, 683 
DefaultTreeSelectionModel class, 670 
JList class, 465 
JTree class, 629 
selectionEnd property 
JTextComponent class, 524 
selectionForeground property 
JList class, 465 
JTable class, 681, 682 
selectionForKey() method 
KeySelectionManager interface, 494 
selectionMode property 
DefaultListSelectionModel class, 475 
DefaultTreeSelectionModel class, 670 
JList class, 465, 475 
JTable class, 681-682 
selectionModel property 
DefaultListSelectionModel class, 683 
DefaultTableColumnModel class, 709 
JColorChooser class, 307 
JList class, 465 
JMenuBar class, 159 
JPopupMenu class, 179 
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JTable class, 682, 683 

JTree class, 629 
selectionPath property 

DefaultTreeSelectionModel class, 670 

JTree class, 629 
selectionPaths property 

DefaultTreeSelectionModel class, 670 

JTree class, 629, 630 
selectionRow property 

JTree class, 629 
selectionRows property 

DefaultTreeSelectionModel class, 670 

JTree class, 629, 630 
selectionStart property 

JTextComponent class, 524 
selectionValues property 

JOptionPane class, 281 
selectionVisible property 

Caret interface, 548 
Separator class, 182 

JToolBar class, 208 
separatorBackground property 

MetalLookAndrFeel class, 773 
separatorForeground property 

MetalLookAndrFeel class, 773 
set() method 

DefaultListModel class, 453 
setAcceptAllFileFilterUsed(O) method 

JFileChooser class, 331 
setAccessibleDescriptionO) method 

AccessibleContext class, 807 
setAccessibleName() method 

AccessibleContext class, 807 
setAction() method 

JComboBox class, 494 

JPopupMenu class, 177 
setAlignment() method 

StyleConstants class, 602 
setBackgroundAt() method 

JTabbedPane class, 398 
setBorder() method 

JViewport class, 412 
setBorderPainted method 

hiding border, 219 
setBorderPainted() method 

JProgressBar component, 441 
setBottomComponent() method 

JSplitPane class, 386 
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setColor() method 
JColorChooser class, 313 
setComponentAt() method 
JTabbedPane class, 398 
setComponentPopupMenu() method 
JComponent class, 178 
setContraints() method 
SpringLayout.Constraints class, 371 
setCorner() method 
JScrollPane class, 409 
setCurrentManager() method 
RepaintManager class, 70 
setDefaultCloseOperation(O) method 
JFrame class, 246 
setDescription() method 
Imagelcon class, 806 
setDisabledIconAt() method 
JTabbedPane class, 398 
setDisplayedMnemonic() method 
JLabel class, 527 
setDisplayedMnemonicIndexAt() method 
JTabbedPane class, 398 
setDividerLocation() method 
JSplitPane class, 387 
setDocumentFilter() method 
AbstractDocument class, 542 
setDot() method 
NavigationFilter class, 552 
setDragEnabled() method 
components with built-in drag-and-drop 
support, 729 
setEditor() method 
JSpinner class, 518 
setElementAt() method 
DefaultListModel class, 453 
setEnabled property 
AbstractButton class, 102 
setEnabled() method 
disables selection of component, 232 
setEnabledAt() method 
JTabbedPane class, 398 
setExtent method 
JScrollBar component, 426 
JSlider component, 431 
setFileFilter() method 
JFileChooser class, 330 
setFocusable() method 
Component class, 49 


setFocusTraversalKeys() method 
Component class, 55 
setForegroundAt() method 
JTabbedPane class, 398 
setHelpMenu() method 
JMenuBar class, 381 
setIconAt() method 
JTabbedPane class, 398 
setIheritsPopupMenu() method 
JComponent class, 178 
setIndeterminate() method 
JProgressBar component, 442 
setInverted() method 
JSlider component, 436 
setltem() method 
ComboBoxEditor class, 499 
set]MenuBar() method 
adding JMenuBar to a window, 157 
setKeymap(O method 
JTextComponent class, 586 
setLabelFor() method 
JLabel class, 528, 807 
setLabelTable() method 
JSlider component, 435 
setLayer() method 
JLayeredPane class, 240 
setLayout() method 
Container class, 344 
JToolBar class, 204 
setLayoutOrientation() method 
JList class, 479 
setLookAndFeel() method 
UlManager class, 743 
setMajorTickSpacing(O) method 
JSlider component, 432 
setMask() method 
JFormattedTextField component, 618 
setMaximum method 
JScrollBar component, 426 
JSlider component, 431 
setMinimum method 
JScrollBar component, 426 
JSlider component, 431 
setMinimumSize() method 
JComponent class, 388 
setMinorTickSpacingO method 
JSlider component, 432 
setMnemonic() method 
AbstractButton class, 101 


setMnemonicAt() method 
JTabbedPane class, 398 
setModel() method 
JTree class, 625 
setOrientation() method 
JSeparator class, 182, 208 
setPaintLabels() method 
JSlider component, 435 
setPaintTicks() method 
JSlider component, 432 
setPaintTrack(O) method 
JSlider component, 436 
setParent() method 
MutableTreeNode interface, 660 
setPopupLocation() method 
JComponent class, 178 
setPosition() method 
JLayeredPane class, 241 
setPreviewPanel() method 
JColorChooser class, 309, 320 
setProgress() method 
ProgressMonitor class, 293 
setRowHeight(O method 
JTable class, 682 
setSelected() method 
ButtonGroup class, 118 
setSelectedlconO) method 
JCheckBox class, 127, 128 
JRadioButton class, 136 
setSelectedIndex() method 
JComboBox class, 493 
setSelectedInterval() method 
JList class, 479 
setSelectedItem( method 
JComboBox class, 493 
setSelectedValue() method 
JList class, 479 
setSnapToTicks() method 
JSlider component, 434 
setStringPainted(O) method 
JProgressBar component, 441 
setText() method 
JFormattedTextField component, 615 
JMenultem class, 589 
setTitleAtQ method 
JTabbedPane class, 398 
setToolTipText() method 
JComponent class, 84, 87 
setToolTipTextAt() method 
JTabbedPane class, 398 
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setTopComponent() method 
JSplitPane class, 386 
setTransferHandler() method 
passing in replacement object to be 
transferred, 731 
setUndecorated() method 
JDialog class, 237 
JFrame class, 237 
setValue() method 
JFormattedTextField component, 615 
JOptionPane, 286 
JScrollBar component, 426 
JSlider component, 431 
setValueAt() method 
JTable class, 678 
setVerifyinputWhenFocusTarget(O) method 
InputVerifier interface, 57 
setView() method 
JViewport class, 412 
setVisibleRowCount() method 
JList class, 467 
sharedInstance() method 
ToolTipManager class, 86 
shouldSelectCell) method 
CellEditor interface, 655 
show() method 
Popup class, 200 
showDialogO) method 
JColorChooser class, 304, 305, 314 
JFileChooser class, 327 
showGrid property 
JTable class, 682 
showHorizontalLines property 
JTable class, 682 
showing property 
JComponent class, 79 
showInputDialog(O) method 
JOptionPane class, 276, 278 
showInternalInputDialog(O) method 
JOptionPane class, 278 
showInternalMessageDialog() method 
JOptionPane class, 277 
showInternalOptionDialog() method 
JOptionPane class, 280 
showInternalXXXDialog() methods 
JOptionPane class, 274 
showMessageDialog(O) method 
JOptionPane class, 277 
showOptionDialog(O) method 
JOptionPane class, 280 
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showsRootHandles property 
JTree class, 629, 630 
showVerticalLines property 
JTable class, 682 
showXXXDialogO methods 
JOptionPane class, 274, 275 
siblingCount property 
DefaultMutableTreeNode interface, 663 
simple numeric text field verification 
example, 56-57 
SimpleAttributeSet class, 585 
creating, 598 
implementation of MutableAttributeSet 
interface, 595 
introduction, 597 
properties, 598 
using, 598-601 
SINGLE_INTERVAL_ SELECTION mode 
ListSelectionModel interface, 474 
SINGLE_SELECTION mode 
ListSelectionModel interface, 474 
SINGLE_TREE_SELECTION mode 
TreeSelectionModel interface, 669 
SingleSelectionModel interface 
introduction, 161 
size property 
DefaultComboBoxModel class, 461 
DefaultListModel class, 453 
JComponent class, 77 
SizeRequirements class, 370 
SmallAttributeSet class, 595 
snapToTicks property 
JSlider component, 431, 434 
SoftBevelBorder class, 222 
constructors, 223 
SortingFocusTraversalPolicy 
FocusTraversalPolicy class, 53 
spinner property 
DefaultEditor class, 518 
SpinnerDateModel class 
getValue() method, 515 
introduction, 514-515 
properties, 515 
SpinnerListModel class 
introduction, 515-516 
properties, 516 
subclassing, 517-518 
working with ListEditor class, 519 


SpinnerModel interface 
data model for JSpinner, 513 
properties, 515 
SpinnerNumberModel class 
introduction, 516-517 
properties, 517 
SpringLayout class 
Constraints inner class, 371 
introduction, 371-375 
SpringLayout.Constraints class, 371 
setContraints() method, 371 
StackOverflowError, 214 
start property 
SpinnerDateModel class, 515 
start() method 
Timer class, 35 
startOffset property 
HTMLDocument.Iterator class, 609 
startPosition property 
AbstractDocument class, 540 
state of text properties 
JTextComponent class implementation 
properties, 525 
state property 
JCheckBoxMenultem component, 185 
StateEdit class, 783 
as UndoableEdit implementation, 800-801 
end() method, 801 
example with StateEditable, 801-804 
StateEditable interface 
example with StateEdit class, 801-804 
implementation of updated document, 800 
methods, 800 
restoreState() method, 801 
stepSize property 
SpinnerNumberModel class, 517 
stop() method 
Timer class, 35 
stopCellEditing(O) method 
CellEditor interface, 654 
storeState method 
StateEditable interface, 800 
StreamDescriptionProperty constant 
Document interface, 531 
string property 
JProgressBar component, 441 
StringContent class 
AbstractDocument.Content 
implementation, 596 


stringPainted property 
JProgressBar component, 441 
strut, creating, 382-383 
Style interface, 595 
introduction, 606 
setting JTextPane text attributes, 580 
StyleConstants class, 595 
constants, 601-602 
introduction, 601 
methods, 602-603 
sharing between multiple documents, 596 
StyleContext class 
introduction, 606 
StyleContext.NamedStyle class, 606 
StyleContext.SmallAttributeSet class, 595 
StyledDocument interface, 521 
Document interface extension of, 595 
extending Document interface, 595 
implemented by DefaultStyledDocument 
class, 596 
loading JTextPane class with content, 
582-583 
manages Style objects, 595 
using with JTextField class, 530 
styledDocument property 
JTextPane class, 581 
StyledDocument.NamedStyle class, 595 
StyledEditorkit class 
finding actions, 591 
styleNames property 
DefaultStyledDocument class, 596 
subElements property 
JMenu class, 172 
JMenuBar class, 159 
JMenultem class, 164 
JPopupMenu class, 179 
subTextFont property 
MetalLookAndrFeel class, 773 
supportedLookAndEeel property 
LookAndFeel class, 742 
surrendersFocusOnKeystroke property 
JTable class, 682 
Swing 
advanced containers, 377 
Box class, 377-383 
JScrollPane class, 403-412 
JSplitPane class, 383-394 
JTabbedPane class, 394-403 
JViewport class, 412-417 
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client properties, 759-763 
introduction, 1 
layout management, 10, 11 
menus, 151 
JCheckBoxMenultem class, 184-189 
JMenu class, 168-175 
JMenuBar class, 157-161 
JMenultem class, 162-168 
JPopupMenu class, 176-184 
JRadioButtonMenultem class, 189-195 
JSeparator class, 175-176 
menu class hierarchy, 156 
MenuElement interface, 195-199 
SingleSelectionModel interface, 161-162 
working with, 152-156 
pop-ups, 200-202 
toolbars, 151 
JToolBar class, 202-208 
Swing components, 2 
See also text components 
AbstractButton class, 98-103 
AWT component replacements, 3 
chapter mapping, 12 
containers compared to AWT 
containers, 235 
delegates, 763-765 
distinction between equivalent AWT 
components, 3 
event handling, 10-11 
GrayFilter class, 97 
Icon interface, 92-94 
Imagelcon class, 94-97 
JButton class, 104-110 
JComponent class, 67 
component pieces, 69-73 
events, 80-84 
properties, 74-79 
JLabel class, 88-92 
JPanel class, 110-112 
JToolTip class, 84-88 
layout managers, 343 
non-AWT upgraded components, 5 
predefined models, 64 
resizing, 388 
scrolling support, 406 
SwingSet demonstration, 11 
undo framework, 11 
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Swing focus management, 46, 47 
examining focus cycles, 50-52 
FocusTraversalPolicy class, 52, 53, 55 
KeyboardFocusManager class, 55 
moving the focus, 48-50 
verifying input during focus traversal, 

56-57 

swing.auxiliarylaf property 

registering auxiliary look and feel 
classes, 776 

swing.properties file, 746 

SwingPropertyChangeSupportt class, 29 

SwingSet demonstration, 11 

Swing-specific event handling, 37 
AbstractAction class, 38-41 
Action interface, 37-38 
KeyStroke class41-45 

mnemonics and accelerators, 46 

SwingUtilities class 
getSharedOwnerFrame() method, 277 
isEventDispatchThread(O) method, 21 
mouse button identification, 23, 24, 26 
updateComponentTreeUI( method, 743 
wrapper methods, 23 

synchronous painting 
JComponent class, 70 

SynthLookAndFeel class, 777 
configuring, 777,779 
default properties, 780 
working with Synth images, 780-781 

SystemColor class 
displaying list of colors from, 311 

SystemColorChooserPanel class, 312, 313 
changing color chooser, 313 
complete source, 314-318 

systemLookAndFeelClassName property 
UlManager class, 748 

systemTextFont property 
MetalLookAndrFeel class, 773 


T 
tabCount property 
JTabbedPane class, 399 
tabLayoutPolicy property 
JTabbedPane class, 399 
table property 
JTableHeader class, 716 


TableCellEditor class, 676, 719, 723 
defining, 722 
editing table cells, 718 
TableCellRenderer interface, 676 
display of cells within table, 676 
getTableCellRendererComponent() 
method, 686, 687 
TableColumn class, 676 
creating, 712 
introduction, 712 
properties, 713 
removing column headers, 680 
using icons in column headers, 713-715 
TableColumnModel interface, 676 
definition, 708 
handling JTable events, 689 
introduction, 708 
listening for TableColumnModelEvent 
objects, 709 
removing TableColumn, 712 
specifying when creating JTable class, 678 
storing column selection model, 683 
TableColumnModelEvent class 
properties, 709 
TableColumnModelListener 
attaching to TableColumnModel 
object, 710 
listening to JTable events, 709-712 
tableHeader property 
JTable class, 682 
TableModel interface, 676 
AbstractTableModel class, 691-696 
default implementation, 695 
DefaultTableModel class, 696-700 
getColumnClass() method, 687, 695 
handling JTable events, 689 
implemented by AbstractTableModel 
class, 691 
introduction, 690 
leaving TableColumn in, 712 
ordering stored columns of data, 676 
sorting JTable elements, 700-707 
using column order of, 678 
TableModelEvent class 
properties, 699 
TableModelListener interface 
list managed by AbstractTableModel 
class, 691 
listening to JTable events, 699 


tables, 675 
editing table cells 
creating complex cell editor, 722-724 
creating simple cell editor, 718-722 
editing table cells, 718-724 
introducing, 675-676 
JTable class, 677-690 
JTableHeader class, 715-718 
printing tables, 724-727 
TableColumnModel interface 
DefaultTableColumnModel class, 
708-709 
listening to JTable events with 
TableColumnModelListener, 
709-712 
TableColumn class, 712-715 
TableColumnModel interface, 707-708, 712 
TableModel interface, 690 
AbstractTableModel class, 691-696 
DefaultTableModel class, 696-700 
sorting JTable elements, 700-707 
tabPlacement property 
JTabbedPane class, 399 
tabRunCount property 
JTabbedPane class, 399 
TabSet attribute 
ParagraphConstants class, 603 
TabSet class 
introduction, 603 
tabSize property 
JTextArea class, 571 
TabStop class 
alignment settings, 604 
creating, 603 
introduction, 603 
properties, 604 
using, 605-606 
tag property 
HTMLDocument.Iterator class, 609 
tearOff property 
JMenu class, 172 
text capabilities, 585 
creating styled text, 595-607 
editor kits, 607-612 
JFormattedTextField component, 612-621 
using actions, 585-594 
text components 
finding actions, 591-594 
JFormattedTextField class, 566-570 
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JPasswordField class, 563-566 
JTextArea class, 570-580 
JTextComponent class, 523-526 
JTextField class, 526-563 
JTextPane class, 580-583 
listing actions, 586-589 
overview, 521-522 
using actions, 585-586, 589-591 
text justification 
TitledBorder class, 230 
text property 
AbstractButton class, 99 
JEditorPane class, 575 
JLabel class, 89 
JTextComponent class, 524 
TextAction class, 522, 585 
as extension of AbstractAction class, 535 
listing text actions, 587 
provides concrete Action 
implementations, 585 
Swing-specific event handling, 37 
using, 586 
TextField class 
selectionBackground property, 547 
textField property 
DefaultEditor class, 518 
textHighlightColor property 
MetalLookAndrFeel class, 773 
textNonSelectionColor property 
DefaultTreeCellRenderer class, 635 
textSelectionColor property 
DefaultTreeCellRenderer class, 635 
TextUl interface, 60 
TextUtilities class, 537 
thickness property 
LineBorder class, 220 
Timer class 
creating objects, 34 
notifying an ActionListener after a 
predefined number of milliseconds, 
34,35 
properties, 35-36 
using objects, 35 
tipText property 
JToolTip class, 85 
title justification 
TitledBorder class, 230 
title positioning 
TitledBorder class, 231 
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title property 
JInternalFrame class, 255 
TitledBorder class, 229 
titleColor property 
TitledBorder class, 229 
TitledBorder class, 227 
configuring properties, 229 
creating, 228 
customizing look and feel, 232 
titleFont property 
TitledBorder class, 229 
titleJustification property 
TitledBorder class, 229 
titlePosition property 
TitledBorder class, 229 
toArrayQ method 
DefaultListModel class, 460 
toggle buttons, 115 
ButtonGroup class, 116-118 
JCheckBox class, 125-134 
JRadioButton class, 134-149 
JToggleButton class, 119-125 
ToggleButtonModel class, 115-116 
ToggleButtonModel class 
button model for JRadioButtonMenultem 
components, 189 
data model for JCheckBoxMenultem 
class, 184 
defining JToggleButton structure, 119 
introduction, 115-116 
ToggleButtonUI class 
defining JToggleButton structure, 119 
toggleClickCount property 
JTree class, 629, 630 
tolndex property 
TableColumnModelEvent class, 709 
toolkit property 
JComponent class, 79 
ToolTipManager class 
adding element level tooltips, 488 
disabling, 87 
properties, 87 
registering component with, 641 
sharedInstance() method, 86 
unregistering table, 689 
tooltips 
PropertiesList example, 488, 490 
toolTipText property 
JComponent class, 79 


ToolTipTreeCellRenderer class, 642 
topComponent property 
JSplitPane class, 386 
topLevelAncestor property 
JComponent class, 78 
topLevelMenu property 
JMenu class, 172 
totalColumnWidth property 
DefaultTableColumnModel class, 709 
Transferable interface 
creating transferable image object, 734 
java.awt.datatransfer package, 733 
methods, 733 
transferFocus() method 
Component class, 55 
transferFocusBackward() method 
Component class, 55 
transferFocusDownCycle() method 
Container class, 55 
transferFocusUpCycle() method 
Component class, 55 
TransferHandler class 
canImport(O) method, 734 
createTransferable() method, 735 
creating a transferable image object, 734 
importData() method, 735 
introduction, 731 
transferHandler property 
JComponent class, 79 
translate() method 
Graphics class, 214 
tree nodes 
creating proper ComboBox editor for a 
tree, 648 
DefaultMutableTreeNode class, 661-664 
editing, 643 
with CellEditor interface, 644 
with DefaultCellEditor class, 645 
with DefaultTreeCellEditor class, 647 
with TreeCellEditor interface, 644 
MutableTreeNode interface, 660 
traversing trees, 664 
TreeNode interface, 659 
tree tooltips 
working with, 641-643 
TreeCellEditor interface, 644 
creating CheckBoxNodeEditor class, 
653-658 
editing table cells, 718 


editing tree nodes, 623, 644 
getTreeCellEditorComponent() method, 
648, 656 
TreeCellRenderer interface 
creating custom renderer, 637-641 
DefaultTreeCellRenderer class, 635 
implementations, 623 
introduction, 634 
TreeExpansionEvent class, 672 
TreePath getPath(Q) method, 673 
TreeExpansionListener interface, 672 
treeExpansionListeners property 
JTree class, 629 
treelock property 
JComponent class, 79 
TreeModel interface 
DefaultTreeModel class implements, 667 
introduction, 667 
getRoot() method, 666 
storing within DefaultTreeModel class, 624 
working with tree nodes, 659 
TreeModelEvent class 
notifying registered listeners, 668 
TreeModelListener interface 
DefaultTreeModel class manages, 667 
reporting changes to model, 668 
TreeNode interface 
nodes of JTree are implementations of, 624 
traversing trees, 664 
working with tree nodes, 659 
TreePath class, 624 
introduction, 671-672 
trees 
additional expansion events, 672-673 
editing tree nodes, 643-659 
introduction, 623-624 
JTree class, 624-634 
TreeCellRenderer interface, 634-643 
TreeModel interface, 667 
TreeSelectionModel interface, 668-672 
working with tree nodes, 659-667 
TreeSelectionEvent class, 671 
TreeSelectionListener interface, 671 
treeSelectionListeners property 
JTree class, 629 
TreeSelectionModel interface 
DefaultTreeSelectionModel class, 670 
introduction, 668-670 
tree selection management, 624 
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TreeWillExpandListener interface, 673 

treeWillExpandListeners property 
JTree class, 629 

trimToSize() method 
DefaultListModel class, 460 

type property 
ListDataEvent class, 454 
TableModelEvent class, 700 


U 

Ul delegates 
adding, 771-772 
creating, 763-766 

Ul property 
AbstractButton class, 99 
JColorChooser class, 307 
JComboBox class, 492 
JDesktopPane component, 263 
JFileChooser class, 327 
JInternalFrame class, 255 
JLabel class, 90 
JList class, 465 
JMenuBar class, 159 
JMenultem class, 164 
JOptionPane class, 281 
JPopupMenu class, 179 
JProgressBar component, 441 
JRootPane class, 237 
JScrollBar component, 426 
JScrollPane class, 407 
JSeparator class, 175 
JSlider component, 431 
JSpinner class, 510 
JSplitPane class, 386 
JTabbedPane class, 399 
JTable class, 682 
JTableHeader class, 716 
JTextComponent class, 524 
JToolBar class, 203 
JToolTip class, 85 
JTree class, 629 
JViewport class, 412 

UIClassID property 
JButton class, 105 
JCheckBox class, 127 
JCheckBoxMenultem component, 185 
JColorChooser class, 307 
JComboBox class, 492 
JDesktopPane component, 263 
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JEditorPane class, 575 

JFileChooser class, 327 

JFormattedTextField class, 567 

JInternalFrame class, 255 

JLabel class, 90 

JList class, 465 

JMenu class, 172 

JMenuBar class, 159 

JMenultem class, 164 

JOptionPane class, 281 

JPasswordField class, 564 

JPopupMenu class, 179 

JProgressBar component, 441 

JRadioButton class, 136 

JRadioButtonMenultem component, 191 

JRootPane class, 237 

JScrollBar component, 426 

JScrollPane class, 407 

JSeparator class, 175 

JSlider component, 431 

JSpinner class, 510 

JSplitPane class, 386 

JTabbedPane class, 399 

JTable class, 682 

JTableHeader class, 716 

JTextArea class, 571 

JTextField class, 529 

JTextPane class, 581 

JToggleButton class, 120 

JToolBar class, 203 

JToolTip class, 85 

JTree class, 629 

JViewport class, 412 
uiClassID property 

JComponent class, 79 
UlDefaults class 

inner classes, 755 

introduction, 71, 749 

listing properties within JTable, 749-752 
UlDefaults.ActiveValue class, 755 

look and feel properties stored as, 741 
UlDefaults.LazyValue class, 755 

look and feel properties stored as, 741 
UlDefaults.ProxyLazyValue class, 755 
UlManager class 

addAuxiliaryLookAndFeel() method, 776 

checking component settings in 

UlDefaults lookup table, 72 
currently installed look and feel classes 
provided by, 741 


get() method, 758, 763 
getInstalledLookAndFeels() method 
743, 776 

getter methods, 747 

introduction, 747 

properties, 748, 813-846 

put() method, 758 

setLookAndFeel() method, 743 
UlManager.LookAndFeelInfo class, 741 


getInstalledLookAndFeels() method, 742 


introduction, 749 
UlResource interface, 741 
classes that implement, 753-754 
introduction, 753 
UlResource properties, fetching, 72 
Undo Framework, 783 
Command design pattern, 788, 789 
components, 789 
AbstractUndoableEdit class, 791 
CompoundEdit class, 791 


defining custom undoable class, 795-800 


UndoableEdit interface, 789-790 
UndoableEditEvent class, 794 
UndoableEditListener interface, 794 
UndoableEditSupport class, 794 
UndoManager class, 792, 793 


using an outside object to manage Undo 


states, 800 
example, 801-804 
StateEdit class, 801 
StateEditable interface, 800 


using with Swing text components, 784-788 


working with, 783, 784 
undo() method 

CompoundEdit class, 792 

UndoableEdit interface, 790 

UndoManager class, 784 
undoable program example, 795-800 
UndoableDrawingPanel class, 797 
UndoableEdit command 

posting to UndoableEditListener 

objects, 801 

UndoManager class, 788, 799 
UndoableEdit interface, 788 

creating, 797 

definition, 789 

flow between states, 790 

StateEdit class implementation, 800 
UndoableEditEvent class 

edit property, 794 


UndoableEditEvent event 
UndoableEditListener interface, 794 
UndoableEditSupport class, 794 
UndoManager class, 793 

undoableEditHappenedO) method 
listener objects, 794 

UndoableEditListener interface, 794 
attaching to document of component, 784 
managing objects with 

UndoableEditSupport class, 794 
UndoableEditEvent event, 794 
UndoableEditSupport class, 794 
UndoManager class, 784 

undoableEditListeners property 
AbstractDocument class, 540 

UndoableEditSupport class, 801 
addUndoableListener() method, 794 
beginUpdate() method, 794 
endUpdate() method, 794 
managing UndoableEditListener 

objects, 794 
postEdit() method, 794 
UndoableEditListener listener, 794 

UndoManager class, 783 
extending to expose UndoableEdit list, 794 
managing undo and redo capabilities for 

Swing text components, 784 
methods, 792 
UndoableEdit command, 788 

UndoManagerHelper class, 785 
definition, 785, 787 
usingthe Undo Framework with the Swing 

text components, 787 

uninstallChooserPanel(O) method 
AbstractColorChooserPanel class, 313 
unitIncrement property 
JScrollBar component, 422, 426 
updateChooser() method 
AbstractColorChooserPanel class, 313 
updateComponentTreeUI() method 
SwingUtilities class, 743 

update UI) method 
changing look and feel setting of 

component, 813 

upFocusCycle() method 
KeyboardFocusManager class, 55 
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userObject property 
DefaultMutableTreeNode class, 640, 666 
DefaultMutableTreeNode interface, 663 
userObjectPath property 
DefaultMutableTreeNode interface, 663 
userTextColor property 
MetalLookAndrFeel class, 773 
userTextFont property 
MetalLookAndrFeel class, 774 


V 
validateRoot property 
JTextField class, 529 
valid property 
HTMLDocument.Iterator class, 609 
JComponent class, 79 
validateRoot property 
JComponent class, 79 
JRootPane class, 237 
JScrollPane class, 407 
JSplitPane class, 386 
validCharacters property 
MaskFormatter class, 620 
value property 
BoundedRangeModel interface, 419 
JFormattedTextField class, 567 
JOptionPane class, 281, 285 
JProgressBar component, 441 
JScrollBar component, 426 
JSlider component, 431 
JSpinner class, 510 
SpinnerDateModel class, 515 
SpinnerListModel class, 516 
SpinnerNumberModel class, 517 
valueForPathChanged(O method 
TreeModel interface, 667 
valuelsAdjusting property 
BoundedRangeModel interface, 420, 424 
DefaultListSelectionModel class, 475, 683 
JList class, 465 
JScrollBar component, 426 
JSlider component, 431 
ListSelectionEvent class, 476 
Vector class 
creating JTree from, 625-627 


897 


898 


INDEX 


verifyInputWhenFocusTarget property 

JComponent class, 78 
verticalAlignment property 

AbstractButton class, 99, 102 

JLabel class, 90 
verticalScrollBar property 

JScrollPane class, 407 
verticalScrollBarPolicy property 

JScrollPane class, 407 
verticalTextPosition property 

AbstractButton class, 99, 102 

JLabel class, 90 
VetoableChangeListener event handler 

JComponent class, 81 
View class 

displaying Document contents with 

EditorKit class, 607 

view property 

JViewport class, 412 
ViewFactory class 

displaying Document contents with 

EditorKit class, 607 

viewport property 

JScrollPane class, 407 
viewportBorder property 

JScrollPane class, 407 
viewportBorderBounds property 

JScrollPane class, 407 
ViewportLayout class, 371, 412 
viewportView property 

JScrollPane class, 406, 407 
viewPosition property 

JViewport class, 412, 414 
viewRect property 

JViewport class, 412, 413 
viewSize property 

JViewport class, 412, 413 
visible property 

Caret interface, 548 

JComponent class, 79 

JPopupMenu class, 179 
visibleAmount property 

JScrollBar component, 426 
visibleRect property 

JComponent class, 77 
visibleRowCount property 

JList class, 465 

JTree class, 629, 630 


W 
wantsInput property 
JOptionPane class, 281, 285 
warningString property 
JInternalFrame class, 255 
weight 
GridBagConstraints class, 357 
wheelScrollingEnabled property 
JScrollPane class, 407 
white property 
MetalLookAndrFeel class, 774 
width property 
JComponent class, 77 
TableColumn class, 713 
WindowAdapter class 
WindowListener methods, 256 
windowBackground property 
MetalLookAndrFeel class, 774 
WindowConstants interface 
close operation constants, 244 
implemented by JDialog class, 248 
working with JFrame class to manage 
closing operations, 242 
windowDecorationStyle property 
JRootPane class, 237, 244 
class constants, 237 
windowInit() method 
JWindow class, 248 
WindowListener interface 
supported by JFrame class, 246 
WindowAdapter class, 256 
WindowsClassicLookAndFeel 
implementation 
LookAndFeel.supportedLookAndEeel, 747 
WindowsLookAndFeel implementation 
LookAndFeel.supportedLookAndEeel, 742 
using on non-Windows machine, 767-768 
windowTextFont property 
MetalLookAndrFeel class, 774 
windowTitleBackground property 
MetalLookAndrFeel class, 774 
windowTitleForeground property 
MetalLookAndrFeel class, 774 
windowTitlelnactiveBackground property 
MetalLookAndrFeel class, 774 
windowTitlelnactiveForeground property 
MetalLookAndrFeel class, 774 
WORA (write-once, run anywhere), 1 


WrappedPlainView view 
BasicTextAreaUI interface, 60 
wrapStyleWord property 
JTextArea class, 571 
writableAction class constant 
DefaultEditorKit class, 592 
write() method 
JTextComponent class, 531 


Xx 
x property 
JComponent class, 77 


Y 
y property 
JComponent class, 77 
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